AMPR-174 #503: EscalationConsidered telemetry (incl. AMPR-173 #502 base) (#515)

I implemented EscalationConsidered as a sibling CognitiveEvent emitted on every
uncertainty evaluation — including near-misses — with a `fired: Boolean`
discriminator and Urgency.LOW for high-volume telemetry. UncertaintyEscalationEvaluator
publishes Considered first, then EscalationFired when the threshold trips
(causal order at the publish site; bus dispatch remains concurrent).

Because AMPR-173 #502 (EscalationFired) is not yet merged, I stacked its
implementation as the base of this commit so AMPR-174 #503 has a publish
site to extend. The AMPR-173 base adds the CognitiveEvent sealed interface,
EscalationFired data class, evaluator scaffold, EventRegistry/AgentEventApi
hooks, CLI rendering, serialization tests, and docs; AMPR-174 layers the
Considered variant on top of all of those surfaces.

Closes #503

Co-authored-by: Miley Chandonnet <miley@Mileys-Mac-mini.local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizer.kt

@@ -102,6 +102,7 @@ object EventCategorizer {
         is GitEvent.Committed,
         is GitEvent.Pushed,
         is GitEvent.FilesStaged,
+        is CognitiveEvent.EscalationConsidered,
         is MemoryEvent.KnowledgeRecalled,
         is MemoryEvent.KnowledgeStored,
         is NotificationEvent<*>,

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/WatchPresenter.kt

@@ -375,6 +375,10 @@ class WatchPresenter(
             is CognitiveEvent.EscalationFired -> {
                 "Uncertainty escalation: ${event.uncertaintyValue} >= ${event.threshold}"
             }
+            is CognitiveEvent.EscalationConsidered -> {
+                val direction = if (event.fired) ">=" else "<"
+                "Uncertainty considered: ${event.uncertaintyValue} $direction ${event.threshold}"
+            }
             is MemoryEvent.KnowledgeRecalled -> {
                 val count = event.resultsFound
                 if (count > 0) "Recalled $count items (relevance: ${String.format("%.0f%%", event.averageRelevance * 100)})"

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/renderer/EventRenderer.kt

@@ -136,6 +136,7 @@ class EventRenderer(
             is Event.QuestionRaised -> "❓" to magenta
             is Event.TaskCreated -> "📋" to green
             is CognitiveEvent.EscalationFired -> "❓" to red
+            is CognitiveEvent.EscalationConsidered -> "❔" to gray
             is TaskEvent -> "📋" to green
             is FileSystemEvent -> "📄" to cyan
             is GitEvent -> "🪾" to cyan

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizerTest.kt

@@ -87,6 +87,23 @@ class EventCategorizerTest {
         assertEquals(EventSignificance.CRITICAL, significance)
     }
 
+    @Test
+    fun `ROUTINE - EscalationConsidered events are routine telemetry`() {
+        val event = CognitiveEvent.EscalationConsidered(
+            eventId = "evt-escalation-considered",
+            timestamp = Clock.System.now(),
+            eventSource = EventSource.Agent("agent-test"),
+            agentId = "agent-test",
+            uncertaintyValue = 0.42,
+            threshold = 0.7,
+            fired = false,
+            cognitivePhase = null,
+        )
+
+        val significance = EventCategorizer.categorize(event)
+        assertEquals(EventSignificance.ROUTINE, significance)
+    }
+
     @Test
     fun `SIGNIFICANT - TaskCreated events are significant`() {
         val event = Event.TaskCreated(

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/renderer/EventRendererTest.kt

@@ -227,6 +227,22 @@ class EventRendererTest {
         cognitivePhase = null,
     )
 
+    private fun escalationConsideredEvent(
+        eventId: String = "evt-escalation-considered-1",
+        timestamp: Instant = Clock.System.now(),
+        source: EventSource = EventSource.Agent("agent-test"),
+        fired: Boolean = false,
+    ): CognitiveEvent.EscalationConsidered = CognitiveEvent.EscalationConsidered(
+        eventId = eventId,
+        timestamp = timestamp,
+        eventSource = source,
+        agentId = "agent-test",
+        uncertaintyValue = 0.42,
+        threshold = 0.7,
+        fired = fired,
+        cognitivePhase = null,
+    )
+
     @Test
     fun `render TaskCreated event shows task ID, description, and assignment`() {
         val output = captureTerminalOutput { _, renderer ->
@@ -427,6 +443,12 @@ class EventRendererTest {
         }
         assertContains(escalationOutput, "❓")
         assertContains(escalationOutput, "EscalationFired")
+
+        val consideredOutput = captureTerminalOutput { _, renderer ->
+            renderer.render(escalationConsideredEvent())
+        }
+        assertContains(consideredOutput, "❔")
+        assertContains(consideredOutput, "EscalationConsidered")
     }
 
     @Test

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/util/EventTypeParserTest.kt

@@ -51,6 +51,7 @@ class EventTypeParserTest {
     @Test
     fun `parse handles CognitiveEvent types`() {
         assertNotNull(EventTypeParser.parse("EscalationFired"))
+        assertNotNull(EventTypeParser.parse("EscalationConsidered"))
     }
 
     @Test
@@ -165,6 +166,7 @@ class EventTypeParserTest {
         assertTrue(allTypes.contains(Event.QuestionRaised.EVENT_TYPE))
         assertTrue(allTypes.contains(Event.CodeSubmitted.EVENT_TYPE))
         assertTrue(allTypes.contains(CognitiveEvent.EscalationFired.EVENT_TYPE))
+        assertTrue(allTypes.contains(CognitiveEvent.EscalationConsidered.EVENT_TYPE))
 
         // Should have meeting events
         assertTrue(allTypes.contains(MeetingEvent.MeetingScheduled.EVENT_TYPE))

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/CognitiveEvent.kt

@@ -55,6 +55,55 @@ sealed interface CognitiveEvent : Event {
             const val EVENT_TYPE: EventType = "EscalationFired"
         }
     }
+
+    /**
+     * Emitted on every uncertainty evaluation, including near-misses that do not trip the threshold.
+     *
+     * Use this event for telemetry — uncertainty trajectory, calibration analysis, "about to fire"
+     * warnings — not for action signals. When an evaluation also fires, an [EscalationFired] is
+     * published immediately after this event (causal order at the publish site; subscribers cannot
+     * assume cross-event handler ordering because bus dispatch is concurrent).
+     *
+     * Volume warning: uncertainty may be evaluated on every LLM call or tool invocation, producing
+     * thousands of events per agent run. Subscribe only if you have a real use for the data;
+     * non-telemetry consumers should filter this event out. Urgency is [Urgency.LOW] for the same
+     * reason.
+     */
+    @Serializable
+    @SerialName("CognitiveEvent.EscalationConsidered")
+    data class EscalationConsidered(
+        override val eventId: EventId,
+        override val timestamp: Instant,
+        override val eventSource: EventSource,
+        override val urgency: Urgency = Urgency.LOW,
+        override val agentId: AgentId,
+        val uncertaintyValue: Double,
+        val threshold: Double,
+        /** True iff this evaluation also produced an [EscalationFired]. */
+        val fired: Boolean,
+        val cognitivePhase: CognitivePhase?,
+    ) : CognitiveEvent {
+
+        override val eventType: EventType = EVENT_TYPE
+
+        override fun getSummary(
+            formatUrgency: (Urgency) -> String,
+            formatSource: (EventSource) -> String,
+        ): String = buildString {
+            append("Escalation considered for $agentId: uncertainty ")
+            append(uncertaintyValue.formatRatio())
+            append(if (fired) " >= threshold " else " < threshold ")
+            append(threshold.formatRatio())
+            cognitivePhase?.let { append(" [${it.name}]") }
+            append(if (fired) " (fired)" else " (near-miss)")
+            append(" ${formatUrgency(urgency)}")
+            append(" from ${formatSource(eventSource)}")
+        }
+
+        companion object {
+            const val EVENT_TYPE: EventType = "EscalationConsidered"
+        }
+    }
 }
 
 private fun Double.formatRatio(): String {

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/EventRegistry.kt

@@ -32,6 +32,7 @@ object EventRegistry {
 
         // CognitiveEvent types
         CognitiveEvent.EscalationFired.EVENT_TYPE,
+        CognitiveEvent.EscalationConsidered.EVENT_TYPE,
 
         // MeetingEvent types
         MeetingEvent.MeetingScheduled.EVENT_TYPE,

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/api/AgentEventApi.kt

@@ -221,6 +221,26 @@ class AgentEventApi(
             }
         }
 
+    /**
+     * Subscribe to every uncertainty evaluation, including near-misses.
+     *
+     * High-volume telemetry — fires on every evaluation, potentially thousands per agent run.
+     * Subscribe only for telemetry, calibration analysis, or near-miss UI. For action signals
+     * use [onEscalationFired] instead.
+     */
+    fun onEscalationConsidered(
+        filter: EventFilter<CognitiveEvent.EscalationConsidered> = EventFilter.noFilter(),
+        handler: suspend (CognitiveEvent.EscalationConsidered, Subscription?) -> Unit,
+    ): Subscription =
+        eventSerialBus.subscribe<CognitiveEvent.EscalationConsidered, EventSubscription.ByEventClassType>(
+            agentId = agentId,
+            eventType = CognitiveEvent.EscalationConsidered.EVENT_TYPE,
+        ) { event, subscription ->
+            if (filter.execute(event)) {
+                handler(event, subscription)
+            }
+        }
+
     /** Retrieve all events since the provided timestamp, or all if null. */
     suspend fun getRecentEvents(
         since: Instant?,

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/escalation/UncertaintyEscalationEvaluator.kt

@@ -10,10 +10,17 @@ import link.socket.ampere.agents.events.api.AgentEventApi
 import link.socket.ampere.agents.events.utils.generateUUID
 
 /**
- * Evaluates uncertainty against an escalation threshold and publishes the threshold-fired signal.
+ * Evaluates uncertainty against an escalation threshold and publishes:
+ * - [CognitiveEvent.EscalationConsidered] on every evaluation (high-volume telemetry)
+ * - [CognitiveEvent.EscalationFired] when the uncertainty meets or exceeds the threshold
+ *
+ * When both events publish, `EscalationConsidered` is emitted first so consumers tracking
+ * near-misses see the causal order at the publish site. Bus dispatch is concurrent, so
+ * subscribers cannot rely on handler-level cross-event ordering.
  */
 class UncertaintyEscalationEvaluator(
     private val agentId: AgentId,
+    private val publishEscalationConsidered: suspend (CognitiveEvent.EscalationConsidered) -> Unit,
     private val publishEscalationFired: suspend (CognitiveEvent.EscalationFired) -> Unit,
     private val clock: Clock = Clock.System,
 ) {
@@ -23,12 +30,14 @@ class UncertaintyEscalationEvaluator(
         clock: Clock = Clock.System,
     ) : this(
         agentId = agentEventApi.agentId,
+        publishEscalationConsidered = { event -> agentEventApi.publish(event) },
         publishEscalationFired = { event -> agentEventApi.publish(event) },
         clock = clock,
     )
 
     /**
      * @return true when the threshold fired and an [CognitiveEvent.EscalationFired] was published.
+     *   An [CognitiveEvent.EscalationConsidered] is always published, regardless of return value.
      */
     suspend fun evaluate(
         uncertaintyValue: Double,
@@ -44,15 +53,32 @@ class UncertaintyEscalationEvaluator(
             "threshold must be in [0.0, 1.0], was $threshold"
         }
 
-        if (uncertaintyValue < threshold) {
+        val fired = uncertaintyValue >= threshold
+        val source = EventSource.Agent(agentId)
+        val consideredTimestamp = clock.now()
+
+        publishEscalationConsidered(
+            CognitiveEvent.EscalationConsidered(
+                eventId = generateUUID(agentId),
+                timestamp = consideredTimestamp,
+                eventSource = source,
+                agentId = agentId,
+                uncertaintyValue = uncertaintyValue,
+                threshold = threshold,
+                fired = fired,
+                cognitivePhase = cognitivePhase,
+            ),
+        )
+
+        if (!fired) {
             return false
         }
 
         publishEscalationFired(
             CognitiveEvent.EscalationFired(
                 eventId = generateUUID(agentId),
                 timestamp = clock.now(),
-                eventSource = EventSource.Agent(agentId),
+                eventSource = source,
                 urgency = urgency,
                 agentId = agentId,
                 uncertaintyValue = uncertaintyValue,