metadata: id: SDS-053 title: Simulation and Replay Service status: Approved version: 1.0.0 bounded_context: shared satisfies: - PRD-024 - ADR-036 date_created: 2025-12-31 last_updated: 2026-01-02 —

Purpose

Provide deterministic scenario execution infrastructure for validating policy/model changes against semantic state snapshots, producing governance evidence, and feeding pattern learning.

Architecture

Component Diagram

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
┌─────────────────────────────────────────────────────────────────┐
│                  Simulation & Replay Service                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │ Inbound      │  │ Domain       │  │ Outbound               │ │
│  │ Adapters     │  │ Core         │  │ Adapters               │ │
│  ├──────────────┤  ├──────────────┤  ├────────────────────────┤ │
│  │ HTTP API     │→ │ Simulation   │→ │ Snapshot Repository    │ │
│  │ CLI          │  │ Kernel       │  │ Evidence Publisher     │ │
│  │ Event Sub    │  │              │  │ Pattern Oracle Client  │ │
│  └──────────────┘  │ Scenario     │  │ Observability Exporter │ │
│                    │ Parser       │  └────────────────────────┘ │
│                    │              │                              │
│                    │ Diff Engine  │                              │
│                    └──────────────┘                              │
└─────────────────────────────────────────────────────────────────┘

Hexagonal Ports

Inbound Ports (Commands/Queries)

Outbound Ports

Domain Model

Entities

Port	Type	Description
`SimulationPort`	Command	Execute simulation scenarios
`ReplayPort`	Command	Replay manifests against snapshots
`ComparisonPort`	Query	Diff simulated vs production traces
`EvidenceExportPort`	Query	Export evidence bundles

Port	Type	Description
`SnapshotRepositoryPort`	Repository	Read/write semantic state snapshots
`EvidencePublisherPort`	Publisher	Submit evidence to SDS-047
`PatternOraclePort`	Client	Feed patterns to SDS-015
`ObservabilityPort`	Exporter	Emit simulation traces to SDS-030

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
interface Simulation {
  id: SimulationId;                    // ifl:hash of inputs
  snapshotId: SnapshotId;
  manifestId: ManifestId;
  scenario: Scenario;
  status: SimulationStatus;
  createdAt: DateTime;
  completedAt?: DateTime;
  results?: SimulationResults;
  evidenceHash?: IflHash;
}

interface Snapshot {
  id: SnapshotId;                      // ifl:hash of content
  sourceContext: BoundedContextId;
  capturedAt: DateTime;
  expiresAt: DateTime;
  contentHash: IflHash;
  sizeBytes: number;
}

interface Scenario {
  id: ScenarioId;
  name: string;
  description: string;
  inputs: ScenarioInput[];
  assertions: ScenarioAssertion[];
  timeoutMs: number;
}

Value Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
type SimulationStatus =
  | "pending"
  | "running"
  | "completed"
  | "failed"
  | "cancelled";

interface SimulationResults {
  outcomes: Outcome[];
  violations: PolicyViolation[];
  diffSummary?: DiffSummary;
  executionMs: number;
  determinismHash: IflHash;           // Hash of outputs for reproducibility check
}

interface Outcome {
  entityId: string;
  entityType: string;
  beforeState: Record<string, unknown>;
  afterState: Record<string, unknown>;
  appliedPolicies: PolicyId[];
}

interface PolicyViolation {
  policyId: PolicyId;
  entityId: string;
  message: string;
  severity: "error" | "warning" | "info";
}

interface DiffSummary {
  matchedEvents: number;
  divergedEvents: number;
  missingEvents: number;
  extraEvents: number;
  divergenceDetails: DivergenceDetail[];
}

Commands

CMD-SIM-001: ExecuteSimulation

1
2
3
4
5
6
7
8
9
10
11
12
interface ExecuteSimulationCommand {
  snapshotId: SnapshotId;
  manifestId: ManifestId;
  scenario: Scenario;
  requestId: RequestId;               // Idempotency key
}

interface ExecuteSimulationResult {
  simulationId: SimulationId;
  status: SimulationStatus;
  estimatedCompletionMs?: number;
}

CMD-SIM-002: CaptureSnapshot

1
2
3
4
5
6
7
8
9
10
11
interface CaptureSnapshotCommand {
  sourceContext: BoundedContextId;
  retentionDays: number;
  requestId: RequestId;
}

interface CaptureSnapshotResult {
  snapshotId: SnapshotId;
  capturedAt: DateTime;
  sizeBytes: number;
}

CMD-SIM-003: ReplayManifest

1
2
3
4
5
6
7
8
9
10
11
interface ReplayManifestCommand {
  manifestId: ManifestId;
  snapshotId: SnapshotId;
  compareWithProductionTraceId?: TraceId;
  requestId: RequestId;
}

interface ReplayManifestResult {
  simulationId: SimulationId;
  diffSummary?: DiffSummary;
}

Queries

QRY-SIM-001: GetSimulationResults

1
2
3
4
5
6
7
8
interface GetSimulationResultsQuery {
  simulationId: SimulationId;
}

interface GetSimulationResultsResponse {
  simulation: Simulation;
  results?: SimulationResults;
}

QRY-SIM-002: ExportEvidence

1
2
3
4
5
6
7
8
9
10
interface ExportEvidenceQuery {
  simulationId: SimulationId;
  format: "json" | "cbor";
}

interface ExportEvidenceResponse {
  evidenceBundle: EvidenceBundle;
  evidenceHash: IflHash;
  signature?: Signature;
}

Policies

POL-SIM-001: Determinism

1
2
3
4
5
6
policy simulation_determinism
  per Constraint Obligation priority 10
  @rationale "Ensures reproducible simulation results"
as:
  forall s in simulations:
    (replay(s.inputs) = s.results.determinismHash)

POL-SIM-002: Isolation

1
2
3
4
5
6
policy simulation_isolation
  per Constraint Prohibition priority 10
  @rationale "Simulations must not affect production state"
as:
  forall s in simulations:
    (s.productionMutations = 0)

POL-SIM-003: Evidence Integrity

1
2
3
4
5
6
policy evidence_integrity
  per Constraint Obligation priority 10
  @rationale "Evidence bundles must be tamper-evident"
as:
  forall e in evidence_bundles:
    (verify_hash(e.content, e.evidenceHash) = true)

Events

EVT-SIM-001: SimulationCompleted

1
2
3
4
5
6
7
8
interface SimulationCompletedEvent {
  eventId: EventId;
  simulationId: SimulationId;
  status: "completed" | "failed";
  resultsHash?: IflHash;
  completedAt: DateTime;
  executionMs: number;
}

EVT-SIM-002: SnapshotCaptured

1
2
3
4
5
6
7
interface SnapshotCapturedEvent {
  eventId: EventId;
  snapshotId: SnapshotId;
  sourceContext: BoundedContextId;
  capturedAt: DateTime;
  sizeBytes: number;
}

Integration Points

NFR Specifications

Implementation Notes

Snapshot Storage

System	Integration	Protocol
SDS-015 Temporal Database	Pattern submission	gRPC
SDS-030 Observability	Trace correlation	OTLP
SDS-047 GovernedSpeed™	Evidence submission	HTTP/REST
SDS-050 Identity	Hash verification	Library
REF-011 Manifest	Schema validation	JSON Schema

NFR	Specification
Latency	< 5s for 1K entity snapshot simulation
Throughput	10 concurrent simulations per tenant
Storage	Snapshots compressed with zstd, 90-day retention
Determinism	100% reproducibility verified on nightly regression

1
2
3
4
5
6
7
8
9
10
11
12
13
# Snapshot storage configuration
snapshot:
  storage:
    backend: s3  # or filesystem
    bucket: sea-simulation-snapshots
    compression: zstd
    encryption: aes-256-gcm
  retention:
    default_days: 90
    max_days: 365
  limits:
    max_size_mb: 500
    max_snapshots_per_context: 100

Scenario Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Example scenario definition
id: scn-policy-threshold-test
name: "Test new approval threshold"
description: "Validate $10K → $5K threshold change"
inputs:
  - type: policy_override
    policy_id: POL-APPROVAL-001
    new_value:
      threshold: 5000
assertions:
  - type: violation_count
    operator: gte
    value: 0
  - type: affected_entities
    operator: exists
timeout_ms: 30000

Type	ID	Document
ADR	ADR-036	Simulation and Replay Architecture
PRD	PRD-024	Simulation & Replay Platform
SDS	SDS-015	Temporal Database Service
SDS	SDS-030	Semantic Observability
SDS	SDS-047	GovernedSpeed™ Governance Runtime
REF	REF-011	Manifest Schema

SDS-053: Simulation and Replay Service