kami/correx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(concept): heuristic concept compiler (ACR fold-in)

Browse Source 
Promotes recurring validated failure->fix patterns into L3 as retrieval-on-demand
concepts. Deterministic core: ConceptCompilerProjection clusters
RetryAttempted->StageCompleted pairs by fingerprint (gate-agnostic), promotes at
N=3 cross-session validated fixes, never-contradicted. ConceptPromotedEvent is the
sole authoritative write (idempotent under replay); ConceptCompilerService appends
it + best-effort injects to L3 (non-authoritative, inv #6). Wired live in
ServerModule.start() on StageCompleted.

Design: docs/plans/2026-07-12-acr-concept-compiler.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DhFXmKe4WisSSPf9LrmmTg
This commit is contained in:
kami
2026-07-15 13:35:17 +04:00
parent d69cb12ce9
commit 3a48ecd24f
9 changed files with 525 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/kernel/src/main/kotlin/com/correx/core/kernel/concept/ConceptCompilerProjection.kt
+100
View File
@@ -0,0 +1,100 @@
package com.correx.core.kernel.concept
import com.correx.core.events.events.ConceptPromotedEvent
import com.correx.core.events.events.RetryAttemptedEvent
import com.correx.core.events.events.StageCompletedEvent
import com.correx.core.events.events.StageFailedEvent
import com.correx.core.events.events.StoredEvent
import com.correx.core.events.events.WorkflowFailedEvent
import com.correx.core.sessions.projections.Projection
/** Default validated-fix count a fingerprint must reach before promotion (design §"Promotion rule"). */
const val DEFAULT_PROMOTION_THRESHOLD = 3
/** A recurring failure signature and its resolution tally, keyed by [RetryAttemptedEvent.fingerprint]. */
data class ConceptCluster(
val fingerprint: String,
val gate: String,
// First line of the recurring failure reason — the retrieval-friendly signature.
val signature: String,
// Count of times a stage retrying this fingerprint went on to complete = validated failure→fix.
val validatedFixes: Int = 0,
// Any StageFailed / WorkflowFailed observed while this fingerprint was open: the fix did NOT hold.
val contradicted: Boolean = false,
)
/** A fingerprint currently being fought by a stage — resolved by the next StageCompleted/Failed. */
data class OpenFailure(val fingerprint: String, val gate: String, val signature: String)
data class ConceptCompilerState(
val clusters: Map<String, ConceptCluster> = emptyMap(),
// fingerprints already emitted as ConceptPromotedEvent — folded back so replay never re-promotes.
val promoted: Set<String> = emptySet(),
// Per-stage open failure the stage is retrying; keyed by "sessionId/stageId" so concurrent sessions
// in one cross-session fold don't collide.
val open: Map<String, OpenFailure> = emptyMap(),
) {
/**
* Clusters that have earned promotion but haven't been emitted yet: validated ≥ [threshold], never
* contradicted, not already promoted. Pure — the caller (a service) appends the ConceptPromotedEvent.
*/
fun promotable(threshold: Int = DEFAULT_PROMOTION_THRESHOLD): List<ConceptCluster> =
clusters.values.filter {
it.fingerprint !in promoted && !it.contradicted && it.validatedFixes >= threshold
}
}
/**
* Read-only projection over the event log that clusters validated failure→fix pairs by
* [RetryAttemptedEvent.fingerprint] (gate-agnostic — contract/review/plan-compile/lint/static all
* flow through the same retry event) and tracks which fingerprints are promotable. Fed the full
* cross-session stream by its driver; the fold is deterministic and replayable (invariant #8).
*
* Signal: a stage emits RetryAttemptedEvent(fingerprint=fp) then StageCompleted ⇒ fp was validated-fixed.
* A StageFailed/WorkflowFailed while fp is still open ⇒ the fix didn't hold (contradiction).
*/
class ConceptCompilerProjection : Projection<ConceptCompilerState> {
override fun initial() = ConceptCompilerState()
override fun apply(state: ConceptCompilerState, event: StoredEvent): ConceptCompilerState =
when (val p = event.payload) {
is RetryAttemptedEvent -> {
val key = "${p.sessionId.value}/${p.stageId.value}"
val sig = p.failureReason.lineSequence().firstOrNull()?.take(SIGNATURE_MAX)?.trim().orEmpty()
state.copy(open = state.open + (key to OpenFailure(p.fingerprint, p.gate, sig)))
}
is StageCompletedEvent -> resolve(state, "${p.sessionId.value}/${p.stageId.value}", fixed = true)
is StageFailedEvent -> resolve(state, "${p.sessionId.value}/${p.stageId.value}", fixed = false)
is WorkflowFailedEvent -> failAllInSession(state, p.sessionId.value)
is ConceptPromotedEvent -> state.copy(promoted = state.promoted + p.fingerprint)
else -> state
}
private fun resolve(state: ConceptCompilerState, key: String, fixed: Boolean): ConceptCompilerState {
val failure = state.open[key] ?: return state
val existing = state.clusters[failure.fingerprint]
?: ConceptCluster(failure.fingerprint, failure.gate, failure.signature)
val updated = if (fixed) {
existing.copy(validatedFixes = existing.validatedFixes + 1)
} else {
existing.copy(contradicted = true)
}
return state.copy(
clusters = state.clusters + (failure.fingerprint to updated),
open = state.open - key,
)
}
// A workflow that failed terminally contradicts every fingerprint still open in that session.
private fun failAllInSession(state: ConceptCompilerState, sessionId: String): ConceptCompilerState {
val prefix = "$sessionId/"
var acc = state
state.open.keys.filter { it.startsWith(prefix) }.forEach { acc = resolve(acc, it, fixed = false) }
return acc
}
private companion object {
const val SIGNATURE_MAX = 200
}
}
core/kernel/src/test/kotlin/com/correx/core/kernel/concept/ConceptCompilerProjectionTest.kt
+124
View File
@@ -0,0 +1,124 @@
package com.correx.core.kernel.concept
import com.correx.core.events.events.ConceptPromotedEvent
import com.correx.core.events.events.EventMetadata
import com.correx.core.events.events.EventPayload
import com.correx.core.events.events.RetryAttemptedEvent
import com.correx.core.events.events.StageCompletedEvent
import com.correx.core.events.events.StageFailedEvent
import com.correx.core.events.events.StoredEvent
import com.correx.core.events.events.WorkflowFailedEvent
import com.correx.core.events.types.EventId
import com.correx.core.events.types.SessionId
import com.correx.core.events.types.StageId
import com.correx.core.events.types.TransitionId
import kotlinx.datetime.Instant
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
class ConceptCompilerProjectionTest {
private val projection = ConceptCompilerProjection()
private var seq = 0L
private fun stored(payload: EventPayload, session: String = "s1") = StoredEvent(
metadata = EventMetadata(
eventId = EventId("e${seq++}"),
sessionId = SessionId(session),
timestamp = Instant.parse("2026-01-01T00:00:00Z"),
schemaVersion = 1,
causationId = null,
correlationId = null,
),
sequence = seq,
sessionSequence = seq,
payload = payload,
)
private fun retry(fp: String, stage: String = "impl", session: String = "s1", reason: String = "boom\ndetail") =
stored(
RetryAttemptedEvent(
sessionId = SessionId(session),
stageId = StageId(stage),
attemptNumber = 1,
maxAttempts = 3,
failureReason = reason,
gate = "lint",
fingerprint = fp,
),
session,
)
private fun completed(stage: String = "impl", session: String = "s1") =
stored(StageCompletedEvent(SessionId(session), StageId(stage), TransitionId("t")), session)
private fun failed(stage: String = "impl", session: String = "s1") =
stored(StageFailedEvent(SessionId(session), StageId(stage), TransitionId("t"), "x"), session)
private fun fold(events: List<StoredEvent>) =
events.fold(projection.initial(), projection::apply)
@Test
fun `retry then StageCompleted counts one validated fix`() {
val state = fold(listOf(retry("fp1"), completed()))
assertEquals(1, state.clusters["fp1"]?.validatedFixes)
assertTrue(state.promotable().isEmpty())
}
@Test
fun `three cross-session validated fixes cross the threshold`() {
val state = fold(
listOf(
retry("fp1", session = "sa"), completed(session = "sa"),
retry("fp1", session = "sb"), completed(session = "sb"),
retry("fp1", session = "sc"), completed(session = "sc"),
),
)
assertEquals(3, state.clusters["fp1"]?.validatedFixes)
assertEquals(listOf("fp1"), state.promotable().map { it.fingerprint })
}
@Test
fun `StageFailed while fingerprint open contradicts the cluster`() {
val state = fold(
listOf(
retry("fp1", session = "sa"), completed(session = "sa"),
retry("fp1", session = "sb"), completed(session = "sb"),
retry("fp1", session = "sc"), failed(session = "sc"),
),
)
assertTrue(state.clusters["fp1"]!!.contradicted)
assertTrue(state.promotable().isEmpty())
}
@Test
fun `WorkflowFailed contradicts every open fingerprint in that session`() {
val state = fold(
listOf(
retry("fp1", stage = "a", session = "sa"),
retry("fp2", stage = "b", session = "sa"),
stored(WorkflowFailedEvent(SessionId("sa"), StageId("a"), "dead", true), "sa"),
),
)
assertTrue(state.clusters["fp1"]!!.contradicted)
assertTrue(state.clusters["fp2"]!!.contradicted)
}
@Test
fun `promotion is idempotent - a promoted fingerprint is not promotable again`() {
val base = listOf(
retry("fp1", session = "sa"), completed(session = "sa"),
retry("fp1", session = "sb"), completed(session = "sb"),
retry("fp1", session = "sc"), completed(session = "sc"),
)
val promoted = base + stored(ConceptPromotedEvent(SessionId("sc"), "fp1", "lint", "concept", 3))
assertTrue(fold(promoted).promotable().isEmpty())
}
@Test
fun `signature is the first line of the failure reason`() {
val state = fold(listOf(retry("fp1", reason = "detekt: MagicNumber\ntrace..."), completed()))
assertEquals("detekt: MagicNumber", state.clusters["fp1"]?.signature)
}
}