Add simulation snapshot type hierarchy and capture skeleton

[klinakuf]

Summary

This PR introduces the foundational contracts for simulation snapshot and restore in Slingshot. It does not yet provide end-to-end checkpointing during a live run; instead it establishes the type hierarchy, DES events, core orchestration, and one stub extension so follow-up PRs can add real state capture without renaming the model.

Type hierarchy (common.snapshot)

• SimulationSnapshot — root interface (extensionId(), schemaVersion(), isCompatibleWith())
• CoreSimulationSnapshot — engine state envelope (simulation time, consumed events)
• CompositeSimulationSnapshot — aggregate root combining core + extension-owned snapshots
• Supporting types: SimulationContext, RestoreStatus, SnapshotScope

Each extension owns a concrete SimulationSnapshot implementation (no separate fragment/payload classes).

Event-driven coordination (core.events.snapshot)

Event	Role
SimulationSnapshotRequested	Starts a capture barrier
ExtensionSimulationSnapshotCaptured	Extension returns its SimulationSnapshot
SimulationSnapshotCompleted	Core delivers assembled CompositeSimulationSnapshot
SimulationStateRestoreRequested	Dispatched in pre-sim when restoring
ExtensionSimulationSnapshotRestored	Extension acknowledges restore

Core orchestration

• SnapshotCapableExtension — marker for participating extensions
• SnapshotContributorRegistry — tracks active snapshot contributors per run
• SnapshotCaptureCoordinator — collects contributor snapshots for one request
• CoreSnapshotBehavior — barrier logic (init capture session, collect via @PostIntercept + @Subscribe, assemble composite)
• DefaultSimulationStateValidator — validates snapshot contributor set matches active extensions (schema 1.x only in this PR)
• SimulationDriver.init(..., Optional<CompositeSimulationSnapshot>) — optional restore path; validates before scheduling SimulationStateRestoreRequested ahead of PreSimulationConfigurationStarted

Normal runs are unchanged when init(config, monitor) is used without a snapshot.

First extension: ResourceSimulation

• Implements SnapshotCapableExtension directly on the existing behavior class
• ResourceSimulationSnapshot (schema 1.0.0) — stub: active/passive/linking resource table counts only
• Capture/restore handlers wired via @OnEvent + @Subscribe
• AbstractResourceTable.size() added for stub capture

Tests

New bundle org.palladiosimulator.analyzer.slingshot.core.test with:

• CompositeSimulationSnapshotTest
• DefaultSimulationStateValidatorTest
• SnapshotCaptureCoordinatorTest

Design notes

• schemaVersion is the per-extension snapshot layout version (not bundle/OSGi version). Restore rejects schemas outside 1.x for now.
• Restore is event-driven in pre-sim; extensions decide how to apply their typed snapshot.
• Resource simulation stub intentionally does not capture queues/jobs yet — that is planned for a follow-up PR together with system/usage entity rebind and SSJ scheduled-event restore.

Out of scope (follow-up PRs)

• requestSnapshot() API and engine pause/resume
• Real FCFS/PS/passive queue capture in ResourceSimulationSnapshot
• SimulationEntityRegistry and system/usage snapshot contributors
• SSJ scheduled-event (JobProgressed) restore
• SimulationJob "Restore" subtask wiring

Test plan

• JAVA_HOME=<jdk-17> mvn verify (Tycho requires Java 17; default JDK 23 fails with Unknown OSGi execution environment: JavaSE-23)
• CompositeSimulationSnapshotTest — composite assembly and typed lookup
• DefaultSimulationStateValidatorTest — contributor set match / mismatch
• SnapshotCaptureCoordinatorTest — barrier completes when all contributors present
• Manual: existing simulation workflow still starts without snapshot argument (no behavioral change on default path)

Made with Cursor

[klinakuf]

The capture state and restore state have to be private. I think also the name for the restoration is actually initialization where we initialize the simulation state with a snapshot and it continues from there

[klinakuf]

Addressed the review comment in the latest commit:

1. captureState() / initializeState() are now private on ResourceSimulation — only the event handlers call them.
2. Restore → initialization naming across the snapshot API:
   • SimulationStateRestoreRequested → SimulationStateInitializationRequested
   • ExtensionSimulationSnapshotRestored → ExtensionSimulationSnapshotInitialized
   • RestoreStatus → InitializationStatus
   • restoreState() → initializeState()
   • Driver param restoredState → initializationSnapshot
   • isRequiredForRestore() → isRequiredForInitialization()

SimulationJob subtask label ("Restore") is unchanged — planned for a follow-up when workflow wiring lands.

[snowball77]

The code lacks appropriate documentation. All code should have API Javadoc, the project should document the requirement and the ADR in mADR format in a doc folder

[klinakuf]

Addressed @snowball77's documentation feedback:

Architecture & requirements

• doc/decisions/0001-simulation-snapshot-and-initialization.md — mADR (accepted)
• doc/decisions/README.md — ADR index
• doc/requirements/simulation-snapshot-initialization.md — functional requirements (FR1–FR7, non-goals, future work)
• doc/requirements/README.md
• README.md — links to doc/decisions/ and doc/requirements/

API Javadoc

• All new public types in common.snapshot, core.events.snapshot, core.snapshot, core.extension, core.behavior, core.exceptions, core.api.SimulationDriver, and ResourceSimulationSnapshot
• ResourceSimulation class doc updated for SnapshotCapableExtension

mvn verify (Java 17) passes.