refactor(compact): name compaction entry state

packages/compact/compact-basic/src/region.ts

@@ -56,10 +56,10 @@ interface CompactionTransactionOptions {
   readonly flush?: () => Promise<void>
 }
 
-interface TurnTail {
+interface CompactionEntryState {
-  readonly turn: number | null
+  readonly openTurn: number | null
-  readonly compactionStart: SessionEvent<'compact/start'> | undefined
+  readonly unmatchedCompactionStart: SessionEvent<'compact/start'> | undefined
-  readonly endSeedSeq: number | undefined
+  readonly latestEndSeedSeq: number | undefined
 }
 
 /**
@@ -155,20 +155,24 @@ export async function compactSurfaceRegion(
 ): Promise<CompactionResult> {
   if (options.owner === null) signal?.throwIfAborted()
   const selection = validateSurfaceRegion(session, start, end)
-  const tail = inspectTurnTail(session.events)
+  const entryState = inspectCompactionEntryState(session.events)
-  assertCompactionInactive(tail.compactionStart, tail.endSeedSeq, 'compaction')
+  assertCompactionInactive(
+    entryState.unmatchedCompactionStart,
+    entryState.latestEndSeedSeq,
+    'compaction',
+  )
 
   let owner: number | null
   if (options.owner === null) {
-    if (tail.turn !== null) {
+    if (entryState.openTurn !== null) {
       throw new ManualCompactionError('busy', 'manual compaction: the session already has an open turn')
     }
     owner = null
   } else {
-    if (tail.turn === null) {
+    if (entryState.openTurn === null) {
       throw new Error('compactRegion: no open turn — automatic compaction events must be enclosed in a turn')
     }
-    owner = tail.turn
+    owner = entryState.openTurn
   }
 
   const startEvent = session.append('compact/start', { turn: owner })
@@ -257,17 +261,18 @@ function throwManualFailure(failure: TransactionFailure): never {
 /**
  * Reject a durable unmatched compaction marker unless a later constructor-seed
  * boundary proves that its owner belongs to an earlier session lifecycle.
- * @param compactionStart - latest unmatched opening marker, if any.
+ * @param unmatchedCompactionStart - latest unmatched opening marker, if any.
- * @param endSeedSeq - newest constructor-seed boundary, if any.
+ * @param latestEndSeedSeq - newest constructor-seed boundary, if any.
  * @param stage - operation label included in the busy diagnostic.
  */
 function assertCompactionInactive(
-  compactionStart: SessionEvent<'compact/start'> | undefined,
+  unmatchedCompactionStart: SessionEvent<'compact/start'> | undefined,
-  endSeedSeq: number | undefined,
+  latestEndSeedSeq: number | undefined,
   stage: string,
 ): void {
-  if (compactionStart === undefined
+  if (unmatchedCompactionStart === undefined
-    || (endSeedSeq !== undefined && endSeedSeq > compactionStart.seq)) return
+    || (latestEndSeedSeq !== undefined
+      && latestEndSeedSeq > unmatchedCompactionStart.seq)) return
   throw new ManualCompactionError(
     'busy',
     `${stage}: compaction already in progress; the session compaction lock is already active`,
@@ -280,8 +285,12 @@ function assertCompactionInactive(
  * @param stage - operation label included in the busy diagnostic.
  */
 export function assertNoActiveCompaction(session: Session, stage: string): void {
-  const tail = inspectTurnTail(session.events)
+  const entryState = inspectCompactionEntryState(session.events)
-  assertCompactionInactive(tail.compactionStart, tail.endSeedSeq, stage)
+  assertCompactionInactive(
+    entryState.unmatchedCompactionStart,
+    entryState.latestEndSeedSeq,
+    stage,
+  )
 }
 
 /** Validate one requested surface-position span before asynchronous work begins. */
@@ -474,36 +483,38 @@ function buildSummarizationInput(
   }
 }
 
-/** Inspect turn state, unmatched compaction, and newest seed boundary independently. */
+/** Inspect open-turn, unmatched-compaction, and latest seed-boundary state independently. */
-function inspectTurnTail(events: readonly SessionEvent[]): TurnTail {
+function inspectCompactionEntryState(events: readonly SessionEvent[]): CompactionEntryState {
-  let turn: number | null = null
+  let openTurn: number | null = null
-  let turnStateKnown = false
+  let openTurnStateKnown = false
-  let compactionStart: SessionEvent<'compact/start'> | undefined
+  let unmatchedCompactionStart: SessionEvent<'compact/start'> | undefined
-  let compactionStateKnown = false
+  let compactionEntryStateKnown = false
-  let endSeedSeq: number | undefined
+  let latestEndSeedSeq: number | undefined
   for (let index = events.length - 1; index >= 0; index -= 1) {
     // oxlint-disable-next-line typescript/no-non-null-assertion
     const event = events[index]!
-    if (endSeedSeq === undefined && event.type === 'session/end-seed') {
+    if (latestEndSeedSeq === undefined && event.type === 'session/end-seed') {
-      endSeedSeq = event.seq
+      latestEndSeedSeq = event.seq
     }
-    if (!compactionStateKnown) {
+    if (!compactionEntryStateKnown) {
       if (event.type === 'compact/start') {
-        compactionStart = event
+        unmatchedCompactionStart = event
-        compactionStateKnown = true
+        compactionEntryStateKnown = true
       } else if (event.type === 'compact/end') {
-        compactionStateKnown = true
+        compactionEntryStateKnown = true
       }
     }
-    if (!turnStateKnown) {
+    if (!openTurnStateKnown) {
       if (event.type === 'turn/start') {
-        turn = event.data.turn
+        openTurn = event.data.turn
-        turnStateKnown = true
+        openTurnStateKnown = true
       } else if (event.type === 'turn/end') {
-        turnStateKnown = true
+        openTurnStateKnown = true
       }
     }
-    if (turnStateKnown && compactionStateKnown && endSeedSeq !== undefined) break
+    if (openTurnStateKnown
+      && compactionEntryStateKnown
+      && latestEndSeedSeq !== undefined) break
   }
-  return { turn, compactionStart, endSeedSeq }
+  return { openTurn, unmatchedCompactionStart, latestEndSeedSeq }
 }