feat: inject recalled L3 memory into router context with budget

Record L3 retrieval as an event carrying hit text (invariant #9), then
rebuild router state and inject recalled memories as a SYSTEM L3 layer in
the context pack. Apply token budget: protected frames (L0 immutable +
current user turn) are never dropped; honest budgetUsed is reported and
'BudgetExceeded' is flagged in appliedStrategies when they overflow. L1/L2
fit newest-first so oldest entries drop first. Emit ContextTruncatedEvent
when entries are dropped. L3MemoryRetrievedEvent is emitted on every CHAT
turn (empty hits reset recalled memory).
This commit is contained in:
2026-05-30 18:40:08 +04:00
parent e6239515bd
commit 8e6a3e1470
6 changed files with 852 additions and 77 deletions
@@ -2,7 +2,7 @@ import com.correx.core.context.model.ContextLayer
import com.correx.core.context.model.ContextPack
import com.correx.core.context.model.EntryRole
import com.correx.core.context.model.TokenBudget
import kotlinx.coroutines.runBlocking
import com.correx.core.events.events.L3RetrievedHit
import com.correx.core.events.types.SessionId
import com.correx.core.events.types.StageId
import com.correx.core.router.DefaultRouterContextBuilder
@@ -13,6 +13,7 @@ import com.correx.core.router.model.RouterTurn
import com.correx.core.router.model.StageOutcomeKind
import com.correx.core.router.model.TurnRole
import com.correx.core.router.model.WorkflowStatus
import kotlinx.coroutines.runBlocking
import kotlinx.datetime.Clock
import kotlinx.datetime.Instant
import org.junit.jupiter.api.Assertions.assertEquals
@@ -76,27 +77,32 @@ class RouterContextBuilderTest {
}
@Test
fun `build drops entries oldest-first for L2 memory`() {
val short = "ok"
fun `build drops entries oldest-first for L2 memory when budget forces partial drop`() {
// Each L2 entry: "Stage sN (SUCCESS): " + 200-char summary ≈ 55 tokens each.
// Use a config with conversationKeepLast=0 so only L0 + L2 compete for budget.
val configNoConv = RouterConfig(conversationKeepLast = 0, tokenBudget = TokenBudget(limit = 10000))
val builderNoConv = DefaultRouterContextBuilder(configNoConv)
val summary = "x".repeat(200) // ~50 tokens; with prefix "Stage sN (SUCCESS): " ~55 tokens total
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
l2Memory = listOf(
RouterL2Entry(StageId("s1"), short, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T00:00:00Z")),
RouterL2Entry(StageId("s2"), short, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-02T00:00:00Z")),
RouterL2Entry(StageId("s3"), short, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-03T00:00:00Z")),
RouterL2Entry(StageId("s1"), summary, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T00:00:00Z")),
RouterL2Entry(StageId("s2"), summary, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-02T00:00:00Z")),
RouterL2Entry(StageId("s3"), summary, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-03T00:00:00Z")),
),
)
// L0 consumes ~33 tokens; budget 93 leaves ~60 for L2.
// Each L2 entry is ~1 token; all 3 fit
val pack = buildPack(state, TokenBudget(limit = 93))
// L0 ~30 tokens; budget 145 leaves ~115. Two entries (~55 each = ~110) fit; the third (oldest) is dropped.
val pack = runBlocking { builderNoConv.build(state, TokenBudget(limit = 145)) }
val l2Entries = pack.layers[ContextLayer.L2] ?: emptyList()
val remainingStageIds = l2Entries.map { it.sourceId }.toSet()
assertEquals(3, l2Entries.size)
assertTrue(remainingStageIds.contains("s1"))
assertTrue(remainingStageIds.contains("s2"))
assertTrue(remainingStageIds.contains("s3"))
val retainedIds = l2Entries.map { it.sourceId }.toSet()
// Newest two survive; oldest is dropped
assertEquals(2, l2Entries.size, "Only 2 of 3 L2 entries should fit")
assertFalse(retainedIds.contains("s1"), "Oldest L2 entry (s1) should be dropped first")
assertTrue(retainedIds.contains("s2"), "Second-newest L2 entry (s2) should be retained")
assertTrue(retainedIds.contains("s3"), "Newest L2 entry (s3) should be retained")
assertEquals(1, pack.compressionMetadata.entriesDropped)
}
@Test
@@ -182,10 +188,10 @@ class RouterContextBuilderTest {
)
val pack = buildPack(state, TokenBudget(limit = 50))
val l0Entries = pack.layers[ContextLayer.L0] ?: emptyList()
val l1Entries = pack.layers[ContextLayer.L1] ?: emptyList()
val l2Entries = pack.layers[ContextLayer.L2] ?: emptyList()
assertEquals(2, l0Entries.size)
assertEquals(0, l1Entries.size)
// The current (last) user turn is always protected and present even at budget=50
assertEquals(1, (pack.layers[ContextLayer.L1] ?: emptyList()).size)
assertEquals(0, l2Entries.size)
assertTrue(pack.compressionMetadata.entriesDropped > 0)
}
@@ -195,8 +201,11 @@ class RouterContextBuilderTest {
// --------------------------------------------------------------------------
@Test
fun `L2 entries are evicted in insertion order (oldest first)`() {
val configTight = RouterConfig(conversationKeepLast = 0, tokenBudget = TokenBudget(limit = 10))
fun `L2 entries are evicted oldest-first and retained in chronological order`() {
// Each L2 entry: "Stage sN (SUCCESS): " + 100-char summary ≈ 30 tokens each.
// L0 ~30 tokens; budget 90 leaves ~60. Two entries (~30 each = ~60) fit; oldest dropped.
val summary = "x".repeat(100) // ~25 tokens; with prefix ~30 tokens total
val configTight = RouterConfig(conversationKeepLast = 0, tokenBudget = TokenBudget(limit = 10000))
val builderTight = DefaultRouterContextBuilder(configTight)
val baseTime = Instant.parse("2026-01-01T00:00:00Z")
val state = RouterState(
@@ -204,16 +213,25 @@ class RouterContextBuilderTest {
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
l2Memory = listOf(
RouterL2Entry(StageId("s1"), "old", StageOutcomeKind.SUCCESS, baseTime),
RouterL2Entry(StageId("s2"), "mid", StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T01:00:00Z")),
RouterL2Entry(StageId("s3"), "new", StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T02:00:00Z")),
RouterL2Entry(StageId("s1"), summary, StageOutcomeKind.SUCCESS, baseTime),
RouterL2Entry(StageId("s2"), summary, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T01:00:00Z")),
RouterL2Entry(StageId("s3"), summary, StageOutcomeKind.SUCCESS, Instant.parse("2026-01-01T02:00:00Z")),
),
)
// L0 consumes ~33 tokens; budget 76 leaves ~43 for L2.
// Each L2 entry is ~1 token; all 3 fit
val pack = runBlocking { builderTight.build(state, TokenBudget(limit = 76)) }
// "Stage sN (SUCCESS): " + 100x = ~30 tokens each; L0 ~30 tokens.
// Budget = L0 (30) + two entries (30+30=60) = 90. Third entry doesn't fit → oldest (s1) dropped.
val pack = runBlocking { builderTight.build(state, TokenBudget(limit = 90)) }
val l2Entries = pack.layers[ContextLayer.L2] ?: emptyList()
assertEquals(3, l2Entries.size)
val retainedIds = l2Entries.map { it.sourceId }
// Oldest entry (s1) should be dropped; s2 and s3 retained in chronological order
assertFalse(retainedIds.contains("s1"), "Oldest L2 entry (s1) should be dropped first")
assertTrue(retainedIds.contains("s2"), "Second L2 entry (s2) should be retained")
assertTrue(retainedIds.contains("s3"), "Newest L2 entry (s3) should be retained")
// Chronological ordering preserved
if (retainedIds.size == 2) {
assertEquals("s2", retainedIds[0], "s2 should appear before s3 in chronological order")
assertEquals("s3", retainedIds[1], "s3 should appear after s2 in chronological order")
}
}
@Test
@@ -516,7 +534,7 @@ class RouterContextBuilderTest {
)
val pack = runBlocking { builder.build(state, TokenBudget(limit = 65)) }
// L0 consumes ~30 tokens, leaving 35 — both L2 entries (each ~130 tokens) dropped
// conversationKeepLast=0 means conversation entry is not included
// conversationKeepLast=0 but the single user turn is the protected current turn; it fits and is not dropped
assertEquals(2, pack.compressionMetadata.entriesDropped)
}
@@ -585,4 +603,361 @@ class RouterContextBuilderTest {
val pack = buildPack(state, TokenBudget(limit = 1000))
assertTrue(pack.id.value.contains("unknown"))
}
// --------------------------------------------------------------------------
// L3 memory injection (slice 2b)
// --------------------------------------------------------------------------
@Test
fun `L3 hits injected into pack ordered by score descending`() {
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "entry-low",
sourceSessionId = SessionId("other"),
sourceTurnId = "turn-low",
text = "low relevance memory",
score = 0.3f,
),
L3RetrievedHit(
entryId = "entry-high",
sourceSessionId = SessionId("other"),
sourceTurnId = "turn-high",
text = "high relevance memory",
score = 0.9f,
),
L3RetrievedHit(
entryId = "entry-mid",
sourceSessionId = SessionId("other"),
sourceTurnId = "turn-mid",
text = "mid relevance memory",
score = 0.6f,
),
),
)
val pack = buildPack(state, TokenBudget(limit = 10000))
val l3Entries = pack.layers[ContextLayer.L3]
assertNotNull(l3Entries)
assertEquals(3, l3Entries!!.size)
// Verify ordering: highest score first
assertEquals("entry-high", l3Entries[0].sourceId)
assertEquals("entry-mid", l3Entries[1].sourceId)
assertEquals("entry-low", l3Entries[2].sourceId)
}
@Test
fun `L3 entries carry recalled memory label in content`() {
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "e1",
sourceSessionId = SessionId("other"),
sourceTurnId = "t1",
text = "some past knowledge",
score = 0.8f,
),
),
)
val pack = buildPack(state, TokenBudget(limit = 10000))
val l3Entry = pack.layers[ContextLayer.L3]?.first()
assertNotNull(l3Entry)
assertTrue(l3Entry!!.content.contains("[recalled memory]"))
assertTrue(l3Entry.content.contains("some past knowledge"))
assertEquals(EntryRole.SYSTEM, l3Entry.role)
assertEquals(ContextLayer.L3, l3Entry.layer)
assertEquals("recalledMemory", l3Entry.sourceType)
}
@Test
fun `L3 hits dropped when budget exhausted and counted in entriesDropped`() {
// Budget tight enough for L0 but not L3 entries with long text
val longText = "x".repeat(800) // ~200 tokens
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "big-entry",
sourceSessionId = SessionId("other"),
sourceTurnId = "t1",
text = longText,
score = 0.9f,
),
),
)
// Budget 50: L0 frame ~30 tokens leaves ~20; L3 entry ~200 tokens -> dropped
val pack = buildPack(state, TokenBudget(limit = 50))
assertTrue(pack.layers[ContextLayer.L3].isNullOrEmpty())
assertEquals(1, pack.compressionMetadata.entriesDropped)
assertTrue(pack.compressionMetadata.truncatedLayers.contains(ContextLayer.L3))
}
// --------------------------------------------------------------------------
// Budget priority: protect system + current user turn, drop oldest first
// --------------------------------------------------------------------------
@Test
fun `system prompt and current user turn survive tight budget`() {
val longContent = "x".repeat(800) // ~200 tokens each
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, longContent, Instant.parse("2026-01-01T00:00:00Z"), turnId = "old-turn"),
RouterTurn(TurnRole.ROUTER, longContent, Instant.parse("2026-01-02T00:00:00Z"), turnId = "mid-turn"),
RouterTurn(TurnRole.USER, "current user input", Instant.parse("2026-01-03T00:00:00Z"), turnId = "current-turn"),
),
)
// Budget 60: L0 frame ~30 tokens -> remaining ~30; current user turn ~4 tokens -> protected.
// Older turns (each ~200 tokens) cannot fit -> dropped.
val pack = buildPack(state, TokenBudget(limit = 60))
val l0 = pack.layers[ContextLayer.L0]
assertNotNull(l0)
assertEquals(2, l0!!.size) // system prompt + workflow status always present
val l1 = pack.layers[ContextLayer.L1] ?: emptyList()
// Current user turn ("current user input") must be present
assertTrue(l1.any { it.content == "current user input" })
// Older turns dropped due to budget
assertFalse(l1.any { it.content == longContent })
assertTrue(pack.compressionMetadata.entriesDropped > 0)
}
@Test
fun `oldest conversation turn is dropped before newest when budget is tight`() {
val config3 = RouterConfig(conversationKeepLast = 3, tokenBudget = TokenBudget(limit = 10000))
val builder3 = DefaultRouterContextBuilder(config3)
val longContent = "x".repeat(800) // ~200 tokens each
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, "oldest turn $longContent", Instant.parse("2026-01-01T00:00:00Z"), turnId = "t1"),
RouterTurn(TurnRole.ROUTER, "middle turn $longContent", Instant.parse("2026-01-02T00:00:00Z"), turnId = "t2"),
RouterTurn(TurnRole.USER, "newest turn", Instant.parse("2026-01-03T00:00:00Z"), turnId = "t3"),
),
)
// Budget 100: L0 frame ~30 tokens -> remaining ~70; newest turn ~3 tokens -> protected.
// Middle turn (~200+) doesn't fit -> dropped. Oldest turn also dropped.
val pack = runBlocking { builder3.build(state, TokenBudget(limit = 100)) }
val l1 = pack.layers[ContextLayer.L1] ?: emptyList()
// Newest turn must survive
assertTrue(l1.any { it.content == "newest turn" })
// Oldest turn should be dropped (too large)
assertFalse(l1.any { it.content.contains("oldest turn") && it.content.contains(longContent) })
assertTrue(pack.compressionMetadata.entriesDropped > 0)
assertTrue(pack.compressionMetadata.truncatedLayers.contains(ContextLayer.L1))
}
@Test
fun `L3 and L2 dropped before recent conversation when budget is tight`() {
val longContent = "x".repeat(200) // ~50 tokens each
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, "current user message", clock.now(), turnId = "curr"),
),
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "l3-entry",
sourceSessionId = SessionId("other"),
sourceTurnId = "l3-turn",
text = longContent,
score = 0.9f,
),
),
l2Memory = listOf(
RouterL2Entry(StageId("s1"), longContent, StageOutcomeKind.SUCCESS, clock.now()),
),
)
// Budget 80: L0 frame ~30 -> remaining ~50; current user turn ~5 -> protected, remaining ~45
// L3 entry ~50 tokens -> just barely doesn't fit (50 > 45) -> dropped
// L2 entry ~50 tokens -> dropped
val pack = buildPack(state, TokenBudget(limit = 80))
val l1 = pack.layers[ContextLayer.L1] ?: emptyList()
// Current user message must survive
assertTrue(l1.any { it.content == "current user message" })
// L3 and L2 must be absent
assertTrue(pack.layers[ContextLayer.L3].isNullOrEmpty())
assertTrue(pack.layers[ContextLayer.L2].isNullOrEmpty())
assertTrue(pack.compressionMetadata.entriesDropped >= 2)
}
@Test
fun `truncatedLayers populated with affected layers when drops occur`() {
val longText = "x".repeat(800)
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, longText, clock.now(), turnId = "old"),
RouterTurn(TurnRole.USER, "current", clock.now(), turnId = "curr"),
),
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "l3e",
sourceSessionId = SessionId("other"),
sourceTurnId = "lt",
text = longText,
score = 0.8f,
),
),
)
val pack = buildPack(state, TokenBudget(limit = 60))
val truncated = pack.compressionMetadata.truncatedLayers
// At least L1 and L3 should be truncated
assertTrue(truncated.isNotEmpty())
}
// --------------------------------------------------------------------------
// N2/B2: protected-frame-overflow — budget smaller than system + current user turn
// --------------------------------------------------------------------------
@Test
fun `budget overflow - system prompt and current user turn present even when they exceed budgetLimit`() {
// Budget so tight that the protected frame alone (system prompt + workflow status) exceeds it.
// The current user turn must still be included; budgetUsed must report the true total;
// appliedStrategies must contain "BudgetExceeded".
val longUserTurn = "x".repeat(200) // ~50 tokens
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, longUserTurn, clock.now(), turnId = "current"),
),
)
// Budget 1: system prompt + workflow status alone exceed this.
val pack = buildPack(state, TokenBudget(limit = 1))
// System prompt must be present
val l0 = pack.layers[ContextLayer.L0] ?: emptyList()
assertTrue(l0.any { it.sourceType == "systemPrompt" }, "System prompt must always be present")
assertTrue(l0.any { it.sourceType == "workflowStatus" }, "Workflow status must always be present")
// Current user turn must be present
val l1 = pack.layers[ContextLayer.L1] ?: emptyList()
assertTrue(l1.any { it.content == longUserTurn }, "Current user turn must be present even when over budget")
// budgetUsed must be the true total (exceeds budgetLimit)
val allEntries = pack.layers.values.flatten()
val trueTotal = allEntries.sumOf { it.tokenEstimate }
assertEquals(trueTotal, pack.budgetUsed, "budgetUsed must report the true token total, not clamped")
assertTrue(pack.budgetUsed > pack.budgetLimit, "budgetUsed must exceed budgetLimit in overflow scenario")
// BudgetExceeded must be signalled in appliedStrategies
assertTrue(
pack.compressionMetadata.appliedStrategies.contains("BudgetExceeded"),
"appliedStrategies must contain 'BudgetExceeded' when frame exceeds budget",
)
}
// --------------------------------------------------------------------------
// S1: conversationKeepLast = 0 must still include the current user turn
// --------------------------------------------------------------------------
@Test
fun `conversationKeepLast zero still includes the current user turn`() {
val configZero = RouterConfig(conversationKeepLast = 0, tokenBudget = TokenBudget(limit = 10000))
val builderZero = DefaultRouterContextBuilder(configZero)
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, "old turn 1", Instant.parse("2026-01-01T00:00:00Z"), turnId = "t1"),
RouterTurn(TurnRole.ROUTER, "old reply", Instant.parse("2026-01-02T00:00:00Z"), turnId = "t2"),
RouterTurn(TurnRole.USER, "current user input", Instant.parse("2026-01-03T00:00:00Z"), turnId = "t3"),
),
)
val pack = runBlocking { builderZero.build(state, TokenBudget(limit = 10000)) }
val l1 = pack.layers[ContextLayer.L1] ?: emptyList()
// conversationKeepLast=0 caps the window to 0 turns, but the protected current turn must appear
assertTrue(l1.any { it.content == "current user input" }, "Current user turn must be present even with conversationKeepLast=0")
// The older turns (capped out) must NOT be present
assertFalse(l1.any { it.content == "old turn 1" }, "Older turns must not appear with conversationKeepLast=0")
assertFalse(l1.any { it.content == "old reply" }, "Older turns must not appear with conversationKeepLast=0")
}
// --------------------------------------------------------------------------
// S4: appliedStrategies includes L3Recall when L3 memory is injected
// --------------------------------------------------------------------------
@Test
fun `appliedStrategies includes L3Recall when lastRetrievedMemory is non-empty`() {
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "e1",
sourceSessionId = SessionId("other"),
sourceTurnId = "t1",
text = "recalled fact",
score = 0.7f,
),
),
)
val pack = buildPack(state, TokenBudget(limit = 10000))
assertTrue(
pack.compressionMetadata.appliedStrategies.contains("L3Recall"),
"appliedStrategies must include 'L3Recall' when L3 memory is injected",
)
}
@Test
fun `appliedStrategies does not include L3Recall when lastRetrievedMemory is empty`() {
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
)
val pack = buildPack(state, TokenBudget(limit = 10000))
assertFalse(
pack.compressionMetadata.appliedStrategies.contains("L3Recall"),
"appliedStrategies must not include 'L3Recall' when no L3 memory is present",
)
}
// --------------------------------------------------------------------------
// N3: ContextPack.layers is sorted by ContextLayer ordinal
// --------------------------------------------------------------------------
@Test
fun `layers map is sorted by ContextLayer ordinal`() {
val state = RouterState(
sessionId = sessionId,
workflowStatus = WorkflowStatus.RUNNING,
currentStageId = stageId,
conversationHistory = listOf(
RouterTurn(TurnRole.USER, "hello", clock.now()),
),
l2Memory = listOf(
RouterL2Entry(StageId("s1"), "summary", StageOutcomeKind.SUCCESS, clock.now()),
),
lastRetrievedMemory = listOf(
L3RetrievedHit(
entryId = "e1",
sourceSessionId = SessionId("other"),
sourceTurnId = "t1",
text = "recalled",
score = 0.5f,
),
),
)
val pack = buildPack(state, TokenBudget(limit = 10000))
val layerKeys = pack.layers.keys.toList()
val ordinals = layerKeys.map { it.ordinal }
assertEquals(ordinals.sorted(), ordinals, "ContextPack.layers must be sorted by ContextLayer ordinal")
}
}