AMPR-183 #530: add ampere-eval Trace primitive (capture, persist, replay)

Introduces the ampere-eval KMP module — the measurement substrate the eval
set is built on:
- Trace / TraceEvent value types (serializable, ordered)
- TraceRecorder that captures an EventSerialBus run stream into a Trace
- SQLDelight-backed TraceService (save / load / list) over its own EvalDatabase
- TraceCursor for partial replay-to-index-N + branch-point signal

Built on the AMPR-188 (#536) recon: corrects the assumed package root to
link.socket.ampere.*, uses the real EventSerialBus (not EventSerializerBus),
and keeps the trace schema in the eval module's own EvalDatabase so production
code never depends on ampere-eval. 14 tests pass (incl. record -> persist ->
load -> replay round-trip).

I (Claude) wrote this commit on Miley's behalf.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: wow-miley

ampere-eval/build.gradle.kts

@@ -0,0 +1,141 @@
+import com.vanniktech.maven.publish.JavadocJar
+import com.vanniktech.maven.publish.KotlinMultiplatform
+import com.vanniktech.maven.publish.SonatypeHost
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jlleitschuh.gradle.ktlint.reporter.ReporterType
+
+plugins {
+    kotlin("multiplatform")
+    kotlin("plugin.serialization")
+    id("app.cash.sqldelight")
+    id("com.vanniktech.maven.publish")
+    id("org.jlleitschuh.gradle.ktlint")
+}
+
+val ampereVersion: String by project
+
+group = "link.socket"
+version = ampereVersion
+
+mavenPublishing {
+    publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
+    signAllPublications()
+
+    configure(KotlinMultiplatform(javadocJar = JavadocJar.Empty()))
+
+    coordinates("link.socket", "ampere-eval", version.toString())
+
+    pom {
+        name.set("Ampere Eval")
+        description.set(
+            "Measurement substrate for AMPERE: capturable, partially-replayable " +
+                "Trace of an EventSerialBus run stream, persisted via SQLDelight.",
+        )
+        url.set("https://github.com/socket-link/ampere")
+        inceptionYear.set("2026")
+
+        licenses {
+            license {
+                name.set("The Apache License, Version 2.0")
+                url.set("https://www.apache.org/licenses/LICENSE-2.0.txt")
+                distribution.set("repo")
+            }
+        }
+
+        developers {
+            developer {
+                id.set("socket-link")
+                name.set("Socket Link")
+                url.set("https://github.com/socket-link")
+            }
+        }
+
+        scm {
+            connection.set("scm:git:git://github.com/socket-link/ampere.git")
+            developerConnection.set("scm:git:ssh://git@github.com:socket-link/ampere.git")
+            url.set("https://github.com/socket-link/ampere")
+        }
+
+        issueManagement {
+            system.set("GitHub Issues")
+            url.set("https://github.com/socket-link/ampere/issues")
+        }
+    }
+}
+
+kotlin {
+    applyDefaultHierarchyTemplate()
+
+    jvm {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_21)
+        }
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    jvmToolchain(21)
+
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                api(project(":ampere-core"))
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
+                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
+                implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
+                implementation("app.cash.sqldelight:runtime:2.2.1")
+            }
+        }
+        val commonTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
+                implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
+            }
+        }
+        val jvmTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+                implementation("app.cash.sqldelight:sqlite-driver:2.2.1")
+            }
+        }
+    }
+}
+
+sqldelight {
+    databases {
+        create("EvalDatabase") {
+            packageName.set("link.socket.ampere.eval.db")
+        }
+    }
+}
+
+tasks.named<Test>("jvmTest") {
+    useJUnitPlatform()
+}
+
+ktlint {
+    verbose.set(true)
+    outputToConsole.set(true)
+    debug.set(true)
+
+    version.set("0.49.1")
+
+    additionalEditorconfig.set(
+        mapOf(
+            "ktlint_code_style" to "intellij_idea",
+        ),
+    )
+
+    filter {
+        exclude { element -> element.file.path.contains("build/") }
+        exclude { element -> element.file.path.contains("generated/") }
+    }
+
+    reporters {
+        reporter(ReporterType.PLAIN)
+        reporter(ReporterType.CHECKSTYLE)
+    }
+}

ampere-eval/src/commonMain/kotlin/link/socket/ampere/eval/trace/Trace.kt

@@ -0,0 +1,64 @@
+package link.socket.ampere.eval.trace
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * A single captured bus event, frozen into an ordered, serializable form.
+ *
+ * @property index zero-based position of this event within its [Trace], in emission order.
+ * @property timestamp epoch milliseconds at which the source event occurred.
+ * @property type the bus event-type discriminator (the source `Event.eventType`),
+ *   used for human/queryable identification — NOT the kotlinx `"type"` payload
+ *   discriminator (which lives inside [payload]).
+ * @property payload the full serialized source event as a [JsonElement]; decodable
+ *   back to the original `Event` via `Event.serializer()` with the shared `DEFAULT_JSON`.
+ */
+@Serializable
+data class TraceEvent(
+    val index: Int,
+    val timestamp: Long,
+    val type: String,
+    val payload: JsonElement,
+)
+
+/**
+ * An ordered, serializable capture of a single run's `EventSerialBus` stream.
+ *
+ * A `Trace` is the one measurement primitive the eval set is built on: evals,
+ * regression gates, and the later reward function are all consumers of a captured,
+ * replayable event stream. Replay is handled by [TraceCursor].
+ *
+ * @property id unique identifier for this trace.
+ * @property runId the run this trace was recorded for (see RECON-trace.md §3).
+ * @property arcId the orchestration pathway (Arc) this run belongs to.
+ * @property createdAt epoch milliseconds when the trace was recorded.
+ * @property events the captured events, in emission order.
+ */
+@Serializable
+data class Trace(
+    val id: String,
+    val runId: String,
+    val arcId: String,
+    val createdAt: Long,
+    val events: List<TraceEvent>,
+) {
+    /** Number of events in the trace. */
+    val size: Int get() = events.size
+
+    /** Events `0..index` inclusive. Delegates to [List.take], so out-of-range is safe. */
+    fun upTo(index: Int): List<TraceEvent> = events.take(index + 1)
+}
+
+/**
+ * Queryable metadata for a persisted [Trace] without its event blob.
+ * Returned by `TraceService.list`.
+ */
+@Serializable
+data class TraceSummary(
+    val id: String,
+    val runId: String,
+    val arcId: String,
+    val createdAt: Long,
+    val eventCount: Int,
+)

ampere-eval/src/commonMain/kotlin/link/socket/ampere/eval/trace/TraceCursor.kt

@@ -0,0 +1,49 @@
+package link.socket.ampere.eval.trace
+
+import kotlinx.serialization.Serializable
+
+/**
+ * A signal marking where replay stops and a fresh ("branched") execution would
+ * take over. The handoff begins at [branchIndex]; [replayed] is the exact prefix
+ * of events to replay before that point.
+ *
+ * Eval is the degenerate case where the handoff never fires: `branchAfter(size - 1)`
+ * replays the whole trace and yields a [branchIndex] one past the last event.
+ */
+@Serializable
+data class BranchPoint(
+    val replayed: List<TraceEvent>,
+    val branchIndex: Int,
+)
+
+/**
+ * Read-only cursor over a [Trace] for partial replay. Live re-execution and the
+ * playback relay are out of scope here (ampere-eval ticket 2).
+ */
+class TraceCursor(private val trace: Trace) {
+
+    /**
+     * Events `0..index` inclusive. The index is coerced into bounds, so this
+     * never throws: values `>= size` return the whole trace, and values `< 0`
+     * (or any index against an empty trace) return an empty list.
+     */
+    fun replayTo(index: Int): List<TraceEvent> =
+        trace.events.take(coerce(index) + 1)
+
+    /**
+     * A [BranchPoint] whose handoff begins at `index + 1`: [BranchPoint.replayed]
+     * is events `0..index`, and [BranchPoint.branchIndex] is the coerced
+     * `index + 1`. `branchAfter(-1)` branches from the very start;
+     * `branchAfter(size - 1)` replays everything.
+     */
+    fun branchAfter(index: Int): BranchPoint {
+        val coerced = coerce(index)
+        return BranchPoint(
+            replayed = trace.events.take(coerced + 1),
+            branchIndex = coerced + 1,
+        )
+    }
+
+    /** Coerce an index into `-1..size-1` (so `+1` lands in `0..size`); `-1` means "before the first event". */
+    private fun coerce(index: Int): Int = index.coerceIn(-1, (trace.size - 1).coerceAtLeast(-1))
+}

ampere-eval/src/commonMain/kotlin/link/socket/ampere/eval/trace/TraceRecorder.kt

@@ -0,0 +1,131 @@
+package link.socket.ampere.eval.trace
+
+import kotlinx.coroutines.channels.Channel
+import kotlinx.datetime.Clock
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.encodeToJsonElement
+import link.socket.ampere.agents.domain.event.Event
+import link.socket.ampere.agents.domain.event.EventRegistry
+import link.socket.ampere.agents.domain.event.EventType
+import link.socket.ampere.agents.events.api.EventHandler
+import link.socket.ampere.agents.events.bus.EventSerialBus
+import link.socket.ampere.agents.events.subscription.Subscription
+import link.socket.ampere.agents.events.utils.generateUUID
+import link.socket.ampere.data.DEFAULT_JSON
+
+/**
+ * Captures a run's `EventSerialBus` stream into a [Trace].
+ *
+ * A recorded trajectory *is* the captured bus stream — there is no parallel
+ * recording channel. The recorder subscribes to every known event type
+ * ([EventRegistry.allEventTypes], the same source of truth the live relay uses),
+ * buffers events in emission order for the recording window, and on stop builds
+ * and persists a [Trace] via [TraceService].
+ *
+ * Scoping note (see RECON-trace.md §3): the base `Event` does not carry a
+ * `runId`, so events are scoped to a run by the *recording window* (start→stop),
+ * and the supplied `runId` / `arcId` are stamped onto the resulting [Trace] as
+ * metadata rather than used to filter individual events.
+ *
+ * @param bus the `EventSerialBus` to capture from (AMPR-183 calls this `EventSerializerBus`).
+ * @param traceService persistence boundary the built [Trace] is saved through on stop.
+ */
+class TraceRecorder(
+    private val bus: EventSerialBus,
+    private val traceService: TraceService,
+    private val json: Json = DEFAULT_JSON,
+    private val eventTypes: List<EventType> = EventRegistry.allEventTypes,
+    private val clockMillis: () -> Long = { Clock.System.now().toEpochMilliseconds() },
+    private val idGenerator: () -> String = { generateUUID() },
+) {
+    /**
+     * Begin recording. Subscribes to the bus immediately; events published after
+     * this call are captured until [RecordingHandle.stop].
+     */
+    fun start(runId: String, arcId: String): RecordingHandle {
+        val buffer = Channel<Event>(Channel.UNLIMITED)
+        val agentId = "trace-recorder/$runId/${idGenerator()}"
+
+        eventTypes.forEach { eventType ->
+            bus.subscribe(
+                agentId = agentId,
+                eventType = eventType,
+                handler = EventHandler<Event, Subscription> { event, _ ->
+                    buffer.trySend(event)
+                },
+            )
+        }
+
+        return RecordingHandle(
+            traceId = idGenerator(),
+            runId = runId,
+            arcId = arcId,
+            createdAt = clockMillis(),
+            buffer = buffer,
+            subscribedTypes = eventTypes,
+            bus = bus,
+            traceService = traceService,
+            json = json,
+        )
+    }
+}
+
+/**
+ * Handle to an in-progress recording. Call [stop] exactly once to finalize.
+ */
+class RecordingHandle internal constructor(
+    private val traceId: String,
+    private val runId: String,
+    private val arcId: String,
+    private val createdAt: Long,
+    private val buffer: Channel<Event>,
+    private val subscribedTypes: List<EventType>,
+    private val bus: EventSerialBus,
+    private val traceService: TraceService,
+    private val json: Json,
+) {
+    /**
+     * Stop recording, build the [Trace] from buffered events (in emission order),
+     * persist it via the [TraceService], and return it.
+     *
+     * Returns failure if persistence fails. Idempotent only insofar as the
+     * channel is drained once; call exactly once.
+     */
+    suspend fun stop(): Result<Trace> {
+        // Stop receiving new events. NOTE: EventSerialBus.unsubscribe removes ALL
+        // handlers for a type (see RECON-trace.md §1) — fine for eval-controlled
+        // runs where the recorder is the sole subscriber.
+        subscribedTypes.forEach { bus.unsubscribe(it) }
+        buffer.close()
+
+        // Dedup by eventId: an event with parentEventTypes is dispatched to more
+        // than one subscribed type (see RECON-trace.md §1/§2), so the recorder may
+        // see it once per matching type. Keep the first arrival, preserving order.
+        val seenEventIds = mutableSetOf<String>()
+        val captured = buildList {
+            while (true) {
+                val event = buffer.tryReceive().getOrNull() ?: break
+                if (seenEventIds.add(event.eventId)) add(event)
+            }
+        }
+
+        val events = captured.mapIndexed { index, event ->
+            TraceEvent(
+                index = index,
+                timestamp = event.timestamp.toEpochMilliseconds(),
+                type = event.eventType,
+                payload = json.encodeToJsonElement(Event.serializer(), event),
+            )
+        }
+
+        val trace = Trace(
+            id = traceId,
+            runId = runId,
+            arcId = arcId,
+            createdAt = createdAt,
+            events = events,
+        )
+
+        return traceService.save(trace).map { trace }
+    }
+}