@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/runtime/compaction/lifecycle.js

@@ -0,0 +1,113 @@
+/**
+ * lifecycle.ts
+ *
+ * Compaction lifecycle state machine for the compaction engine.
+ *
+ * Provides:
+ * - Valid transition map for the 9-state machine
+ * - Pure transition helpers (no side-effects)
+ * - Strategy selection logic based on trigger and token pressure
+ */
+// ---------------------------------------------------------------------------
+// Transition map
+// ---------------------------------------------------------------------------
+/**
+ * Valid state transitions for the compaction lifecycle machine.
+ *
+ * Key   = current state
+ * Value = set of states reachable from current
+ */
+const VALID_TRANSITIONS = new Map([
+    ['idle', new Set(['checking_threshold'])],
+    ['checking_threshold', new Set(['microcompact', 'collapse', 'autocompact', 'reactive_compact', 'done', 'failed'])],
+    ['microcompact', new Set(['boundary_commit', 'failed'])],
+    ['collapse', new Set(['boundary_commit', 'failed'])],
+    ['autocompact', new Set(['boundary_commit', 'failed'])],
+    ['reactive_compact', new Set(['boundary_commit', 'failed'])],
+    ['boundary_commit', new Set(['done', 'failed'])],
+    ['done', new Set(['idle'])],
+    ['failed', new Set(['idle'])],
+]);
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns whether a transition from `from` to `to` is valid.
+ */
+export function canTransition(from, to) {
+    return VALID_TRANSITIONS.get(from)?.has(to) ?? false;
+}
+/**
+ * Returns all states reachable from `from`.
+ */
+export function reachableFrom(from) {
+    return VALID_TRANSITIONS.get(from) ?? new Set();
+}
+/**
+ * Validates and applies a state transition.
+ *
+ * @returns `{ ok: true, state }` on success, `{ ok: false, reason }` on rejection.
+ */
+export function applyTransition(current, target) {
+    if (canTransition(current, target)) {
+        return { ok: true, state: target };
+    }
+    return {
+        ok: false,
+        reason: `Invalid compaction transition: ${current} → ${target}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Terminal / operational helpers
+// ---------------------------------------------------------------------------
+/** Returns true if the state is a terminal completion state (done | failed). */
+export function isTerminal(state) {
+    return state === 'done' || state === 'failed';
+}
+/** Returns true if the state represents active compaction work in progress. */
+export function isCompacting(state) {
+    return (state === 'microcompact' ||
+        state === 'collapse' ||
+        state === 'autocompact' ||
+        state === 'reactive_compact' ||
+        state === 'boundary_commit');
+}
+/**
+ * Selects the appropriate compaction strategy based on trigger and token pressure.
+ *
+ * Selection priority:
+ * 1. `reactive`     — any prompt-too-long error (emergency, must shrink now)
+ * 2. `microcompact` — token pressure < 50% of context window (light touch)
+ * 3. `autocompact`  — token pressure 50–85% (standard auto-compaction)
+ * 4. `collapse`     — token pressure > 85% or manual trigger (aggressive shrink)
+ */
+export function selectStrategy(params) {
+    const { trigger, currentTokens, contextWindow, isPromptTooLong } = params;
+    if (isPromptTooLong === true || trigger === 'prompt_too_long') {
+        return 'reactive';
+    }
+    const pressure = currentTokens / contextWindow;
+    if (pressure < 0.5) {
+        return 'microcompact';
+    }
+    if (pressure < 0.85) {
+        return 'autocompact';
+    }
+    // High pressure or manual trigger — aggressive collapse
+    return 'collapse';
+}
+/**
+ * Maps a chosen CompactionStrategy to its corresponding lifecycle state.
+ */
+export function strategyToState(strategy) {
+    switch (strategy) {
+        case 'microcompact': return 'microcompact';
+        case 'collapse': return 'collapse';
+        case 'autocompact': return 'autocompact';
+        case 'reactive': return 'reactive_compact';
+        default: {
+            const _exhaustive = strategy;
+            throw new Error(`Unknown compaction strategy: ${_exhaustive}`);
+        }
+    }
+}

package/dist/_internal/platform/runtime/compaction/manager.d.ts

@@ -0,0 +1,100 @@
+/**
+ * manager.ts
+ *
+ * CompactionManager — orchestrates the full compaction lifecycle state machine.
+ *
+ * Responsibilities:
+ * - Gate all compaction behind the `session-compaction` feature flag
+ * - Drive state transitions (idle → checking_threshold → strategy → boundary_commit → done/failed)
+ * - Select and execute the appropriate compaction strategy
+ * - Create boundary commits with lineage tracking
+ * - Emit CompactionEvents at each transition
+ * - Expose the resume repair pipeline
+ */
+import type { RuntimeEventBus } from '../events/index.js';
+import type { FeatureFlagManager } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/manager';
+import type { BoundaryCommit, CompactionLifecycleResult, CompactionLifecycleState, CompactionTrigger } from './types.js';
+import type { ResumeRepairResult } from './types.js';
+import type { ProviderMessage } from '../../providers/interface.js';
+/** Options for constructing a CompactionManager. */
+export interface CompactionManagerOptions {
+    /** Session ID for event correlation. */
+    sessionId: string;
+    /** Runtime event bus for emitting CompactionEvents. */
+    bus: RuntimeEventBus;
+    /** Feature flag manager — used to gate on `session-compaction`. */
+    flags: FeatureFlagManager;
+    /** Model context window size (tokens). */
+    contextWindow: number;
+    /** Threshold fraction at which compaction is triggered (default: 0.75). */
+    thresholdFraction?: number;
+}
+/**
+ * CompactionManager — manages the full lifecycle of session context compaction.
+ *
+ * All compaction is gated behind the `session-compaction` feature flag.
+ * When the flag is disabled, `compact()` is a no-op and returns the original
+ * messages unchanged.
+ *
+ * Usage:
+ * ```ts
+ * const manager = createCompactionManager({ sessionId, bus, flags, contextWindow });
+ * const result = await manager.compact({ messages, tokenCount: 45000, trigger: 'auto' });
+ * ```
+ */
+export declare class CompactionManager {
+    private readonly _sessionId;
+    private readonly _bus;
+    private readonly _flags;
+    private readonly _contextWindow;
+    private readonly _thresholdFraction;
+    /** Current state machine state. */
+    private _state;
+    /** Most recent boundary commit (null until first successful compaction). */
+    private _lastCommit;
+    /** Emitter context used for all event emissions. */
+    private readonly _ctx;
+    constructor(opts: CompactionManagerOptions);
+    /** Returns the current lifecycle state. */
+    get state(): CompactionLifecycleState;
+    /** Returns the most recent boundary commit, or null. */
+    get lastCommit(): BoundaryCommit | null;
+    /**
+     * Options for a compaction run.
+     */
+    /**
+     * Runs the compaction lifecycle for the given messages and trigger.
+     *
+     * If the `session-compaction` feature flag is disabled, returns the
+     * original messages unchanged with no events emitted.
+     *
+     * @param opts - Run options.
+     * @returns Lifecycle result, or null if gated/skipped.
+     */
+    compact(opts: {
+        messages: ProviderMessage[];
+        tokenCount: number;
+        trigger: CompactionTrigger;
+        isPromptTooLong?: boolean;
+    }): Promise<CompactionLifecycleResult | null>;
+    /**
+     * Runs the session resume repair pipeline on the last boundary commit.
+     *
+     * If no commit exists, returns a result with the original messages and
+     * a warning action.
+     *
+     * @param overrideCommit - Optional commit to repair (defaults to lastCommit).
+     * @returns ResumeRepairResult.
+     */
+    repair(overrideCommit?: BoundaryCommit): ResumeRepairResult;
+    /**
+     * Executes the selected strategy and emits the corresponding domain event.
+     */
+    private _runStrategy;
+    /**
+     * Applies a state transition, throwing if invalid.
+     * Invalid transitions are logged and treated as internal errors.
+     */
+    private _transition;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/_internal/platform/runtime/compaction/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/compaction/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8DAA8D,CAAC;AAgBvG,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EAExB,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAerD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAOpE,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,GAAG,EAAE,eAAe,CAAC;IACrB,mEAAmE;IACnE,KAAK,EAAE,kBAAkB,CAAC;IAC1B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C,mCAAmC;IACnC,OAAO,CAAC,MAAM,CAAoC;IAElD,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAA+B;IAElD,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;gBAE1B,IAAI,EAAE,wBAAwB;IAe1C,2CAA2C;IAC3C,IAAI,KAAK,IAAI,wBAAwB,CAEpC;IAED,wDAAwD;IACxD,IAAI,UAAU,IAAI,cAAc,GAAG,IAAI,CAEtC;IAED;;OAEG;IAEH;;;;;;;;OAQG;IACG,OAAO,CAAC,IAAI,EAAE;QAClB,QAAQ,EAAE,eAAe,EAAE,CAAC;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,iBAAiB,CAAC;QAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAqN7C;;;;;;;;OAQG;IACH,MAAM,CACJ,cAAc,CAAC,EAAE,cAAc,GAC9B,kBAAkB;IAuBrB;;OAEG;YACW,YAAY;IAmD1B;;;OAGG;IACH,OAAO,CAAC,WAAW;CAepB"}

package/dist/_internal/platform/runtime/compaction/manager.js

@@ -0,0 +1,371 @@
+/**
+ * manager.ts
+ *
+ * CompactionManager — orchestrates the full compaction lifecycle state machine.
+ *
+ * Responsibilities:
+ * - Gate all compaction behind the `session-compaction` feature flag
+ * - Drive state transitions (idle → checking_threshold → strategy → boundary_commit → done/failed)
+ * - Select and execute the appropriate compaction strategy
+ * - Create boundary commits with lineage tracking
+ * - Emit CompactionEvents at each transition
+ * - Expose the resume repair pipeline
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { applyTransition, selectStrategy, strategyToState, } from './lifecycle.js';
+import { runMicrocompact, runCollapse, runAutocompact, runReactive, createBoundaryCommit, validateBoundaryCommit, } from './strategies/index.js';
+import { runResumeRepair } from './resume-repair.js';
+import { emitCompactionCheck, emitCompactionDone, emitCompactionFailed, emitCompactionBoundaryCommit, emitCompactionMicrocompact, emitCompactionCollapse, emitCompactionAutocompact, emitCompactionReactive, emitCompactionQualityScore, emitCompactionStrategySwitch, } from '../emitters/compaction.js';
+import { computeQualityScore, escalateStrategy, LOW_QUALITY_THRESHOLD } from './quality-score.js';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+/**
+ * CompactionManager — manages the full lifecycle of session context compaction.
+ *
+ * All compaction is gated behind the `session-compaction` feature flag.
+ * When the flag is disabled, `compact()` is a no-op and returns the original
+ * messages unchanged.
+ *
+ * Usage:
+ * ```ts
+ * const manager = createCompactionManager({ sessionId, bus, flags, contextWindow });
+ * const result = await manager.compact({ messages, tokenCount: 45000, trigger: 'auto' });
+ * ```
+ */
+export class CompactionManager {
+    _sessionId;
+    _bus;
+    _flags;
+    _contextWindow;
+    _thresholdFraction;
+    /** Current state machine state. */
+    _state = 'idle';
+    /** Most recent boundary commit (null until first successful compaction). */
+    _lastCommit = null;
+    /** Emitter context used for all event emissions. */
+    _ctx;
+    constructor(opts) {
+        this._sessionId = opts.sessionId;
+        this._bus = opts.bus;
+        this._flags = opts.flags;
+        this._contextWindow = opts.contextWindow;
+        this._thresholdFraction = opts.thresholdFraction ?? 0.75;
+        this._ctx = {
+            sessionId: opts.sessionId,
+            source: 'compaction-manager',
+            traceId: crypto.randomUUID(),
+        };
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /** Returns the current lifecycle state. */
+    get state() {
+        return this._state;
+    }
+    /** Returns the most recent boundary commit, or null. */
+    get lastCommit() {
+        return this._lastCommit;
+    }
+    /**
+     * Options for a compaction run.
+     */
+    /**
+     * Runs the compaction lifecycle for the given messages and trigger.
+     *
+     * If the `session-compaction` feature flag is disabled, returns the
+     * original messages unchanged with no events emitted.
+     *
+     * @param opts - Run options.
+     * @returns Lifecycle result, or null if gated/skipped.
+     */
+    async compact(opts) {
+        // ── Feature flag gate ────────────────────────────────────────────────────
+        if (!this._flags.isEnabled('session-compaction')) {
+            logger.debug('[CompactionManager] session-compaction flag disabled; skipping', {
+                sessionId: this._sessionId,
+            });
+            return null;
+        }
+        const runStart = Date.now();
+        const { messages, tokenCount, trigger, isPromptTooLong } = opts;
+        const threshold = Math.floor(this._contextWindow * this._thresholdFraction);
+        // ── Transition: idle → checking_threshold ────────────────────────────────
+        this._transition('checking_threshold');
+        emitCompactionCheck(this._bus, this._ctx, {
+            sessionId: this._sessionId,
+            tokenCount,
+            threshold,
+        });
+        // ── Check threshold ──────────────────────────────────────────────────────
+        if (trigger === 'auto' && !isPromptTooLong && tokenCount < threshold) {
+            // Below threshold — go straight to done without compacting
+            this._transition('done');
+            this._transition('idle');
+            logger.debug('[CompactionManager] below threshold; no compaction needed', {
+                sessionId: this._sessionId,
+                tokenCount,
+                threshold,
+            });
+            return null;
+        }
+        // ── Select strategy ──────────────────────────────────────────────────────
+        let strategy = selectStrategy({
+            trigger,
+            currentTokens: tokenCount,
+            contextWindow: this._contextWindow,
+            isPromptTooLong,
+        });
+        const strategyState = strategyToState(strategy);
+        // ── Transition: checking_threshold → <strategy state> ────────────────────
+        this._transition(strategyState);
+        // ── Execute strategy ─────────────────────────────────────────────────────
+        let strategyOutput;
+        let qualityScore = null;
+        let strategySwitchReason = null;
+        const strategyInput = {
+            sessionId: this._sessionId,
+            messages,
+            tokensBefore: tokenCount,
+            contextWindow: this._contextWindow,
+            strategy,
+            meta: isPromptTooLong !== undefined ? { isPromptTooLong } : undefined,
+        };
+        try {
+            strategyOutput = await this._runStrategy(strategy, strategyInput);
+        }
+        catch (err) {
+            const error = summarizeError(err);
+            this._transition('failed');
+            emitCompactionFailed(this._bus, this._ctx, {
+                sessionId: this._sessionId,
+                strategy,
+                error,
+            });
+            this._transition('idle');
+            logger.error('[CompactionManager] strategy execution failed', {
+                sessionId: this._sessionId,
+                strategy,
+                error,
+            });
+            return null;
+        }
+        // ── Score quality and auto-switch if low ─────────────────────────────────
+        qualityScore = computeQualityScore(strategyInput, strategyOutput);
+        emitCompactionQualityScore(this._bus, this._ctx, {
+            sessionId: this._sessionId,
+            strategy,
+            score: qualityScore.score,
+            grade: qualityScore.grade,
+            compressionRatio: qualityScore.compressionRatio,
+            retentionScore: qualityScore.retentionScore,
+            isLowQuality: qualityScore.isLowQuality,
+            description: qualityScore.description,
+        });
+        if (qualityScore.isLowQuality) {
+            const escalated = escalateStrategy(strategy);
+            if (escalated !== strategy) {
+                const reason = `Quality score ${qualityScore.score.toFixed(2)} below threshold ${LOW_QUALITY_THRESHOLD}; escalating from ${strategy} to ${escalated}`;
+                strategySwitchReason = reason;
+                logger.warn('[CompactionManager] low quality score — switching strategy', {
+                    sessionId: this._sessionId,
+                    fromStrategy: strategy,
+                    toStrategy: escalated,
+                    score: qualityScore.score,
+                    grade: qualityScore.grade,
+                });
+                emitCompactionStrategySwitch(this._bus, this._ctx, {
+                    sessionId: this._sessionId,
+                    fromStrategy: strategy,
+                    toStrategy: escalated,
+                    reason,
+                    score: qualityScore.score,
+                });
+                // Force state to the escalated strategy state, bypassing normal transition
+                // validation. This is intentional: quality-correction reruns are not modelled
+                // in the standard state machine, and forcing the state allows _runStrategy to
+                // emit the correct strategy event while keeping lifecycle state consistent.
+                this._state = strategyToState(escalated);
+                const escalatedInput = { ...strategyInput, strategy: escalated };
+                try {
+                    const escalatedOutput = await this._runStrategy(escalated, escalatedInput);
+                    // Re-score the escalated result
+                    qualityScore = computeQualityScore(escalatedInput, escalatedOutput);
+                    strategyOutput = escalatedOutput;
+                    strategy = escalated;
+                }
+                catch (err) {
+                    const error = summarizeError(err);
+                    logger.warn('[CompactionManager] escalated strategy also failed; using original output', {
+                        sessionId: this._sessionId,
+                        strategy: escalated,
+                        error,
+                    });
+                    // Fall back to the original output — restore to the original strategy state
+                    this._state = strategyToState(strategy);
+                }
+            }
+            else {
+                // Already at ceiling strategy (collapse or reactive) — log but continue
+                logger.debug('[CompactionManager] low quality at ceiling strategy; no escalation possible', {
+                    sessionId: this._sessionId,
+                    strategy,
+                    score: qualityScore.score,
+                });
+            }
+        }
+        // ── Transition: <strategy> → boundary_commit ─────────────────────────────
+        this._transition('boundary_commit');
+        // ── Create boundary commit ───────────────────────────────────────────────
+        const commit = createBoundaryCommit({
+            sessionId: this._sessionId,
+            strategyOutput,
+            parent: this._lastCommit,
+            tokensBefore: tokenCount,
+        });
+        const commitErrors = validateBoundaryCommit(commit);
+        if (commitErrors.length > 0) {
+            const error = commitErrors.join('; ');
+            this._transition('failed');
+            emitCompactionFailed(this._bus, this._ctx, {
+                sessionId: this._sessionId,
+                strategy,
+                error,
+            });
+            this._transition('idle');
+            logger.error('[CompactionManager] boundary commit validation failed', {
+                sessionId: this._sessionId,
+                errors: commitErrors,
+            });
+            return null;
+        }
+        emitCompactionBoundaryCommit(this._bus, this._ctx, {
+            sessionId: this._sessionId,
+            checkpointId: commit.checkpointId,
+        });
+        this._lastCommit = commit;
+        // ── Transition: boundary_commit → done ───────────────────────────────────
+        this._transition('done');
+        const durationMs = Date.now() - runStart;
+        emitCompactionDone(this._bus, this._ctx, {
+            sessionId: this._sessionId,
+            strategy,
+            tokensBefore: tokenCount,
+            tokensAfter: strategyOutput.tokensAfter,
+            durationMs,
+        });
+        // ── Transition: done → idle ───────────────────────────────────────────────
+        this._transition('idle');
+        return {
+            sessionId: this._sessionId,
+            strategy,
+            tokensBefore: tokenCount,
+            tokensAfter: strategyOutput.tokensAfter,
+            durationMs,
+            commit,
+            messages: strategyOutput.messages,
+            warnings: strategyOutput.warnings,
+            qualityScore,
+            strategySwitchReason,
+        };
+    }
+    /**
+     * Runs the session resume repair pipeline on the last boundary commit.
+     *
+     * If no commit exists, returns a result with the original messages and
+     * a warning action.
+     *
+     * @param overrideCommit - Optional commit to repair (defaults to lastCommit).
+     * @returns ResumeRepairResult.
+     */
+    repair(overrideCommit) {
+        const commit = overrideCommit ?? this._lastCommit;
+        if (!commit) {
+            return {
+                sessionId: this._sessionId,
+                repaired: false,
+                actions: [
+                    {
+                        kind: 'no_commit',
+                        description: 'No boundary commit available; nothing to repair.',
+                        severity: 'info',
+                    },
+                ],
+                messages: [],
+                safeToResume: false,
+                failReason: 'No boundary commit available for repair.',
+            };
+        }
+        return runResumeRepair({ commit });
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    /**
+     * Executes the selected strategy and emits the corresponding domain event.
+     */
+    async _runStrategy(strategy, input) {
+        switch (strategy) {
+            case 'microcompact': {
+                const output = runMicrocompact(input);
+                emitCompactionMicrocompact(this._bus, this._ctx, {
+                    sessionId: this._sessionId,
+                    turnCount: input.messages.length,
+                    tokensBefore: input.tokensBefore,
+                    tokensAfter: output.tokensAfter,
+                });
+                return output;
+            }
+            case 'collapse': {
+                const output = runCollapse(input);
+                emitCompactionCollapse(this._bus, this._ctx, {
+                    sessionId: this._sessionId,
+                    messageCount: input.messages.length,
+                    tokensBefore: input.tokensBefore,
+                    tokensAfter: output.tokensAfter,
+                });
+                return output;
+            }
+            case 'autocompact': {
+                const output = runAutocompact(input);
+                emitCompactionAutocompact(this._bus, this._ctx, {
+                    sessionId: this._sessionId,
+                    strategy: 'autocompact',
+                    tokensBefore: input.tokensBefore,
+                    tokensAfter: output.tokensAfter,
+                });
+                return output;
+            }
+            case 'reactive': {
+                const output = runReactive(input);
+                emitCompactionReactive(this._bus, this._ctx, {
+                    sessionId: this._sessionId,
+                    tokenCount: input.tokensBefore,
+                    limit: this._contextWindow,
+                });
+                return output;
+            }
+            default: {
+                const _exhaustive = strategy;
+                throw new Error(`Unknown compaction strategy: ${_exhaustive}`);
+            }
+        }
+    }
+    /**
+     * Applies a state transition, throwing if invalid.
+     * Invalid transitions are logged and treated as internal errors.
+     */
+    _transition(target) {
+        const result = applyTransition(this._state, target);
+        if (!result.ok) {
+            logger.error('[CompactionManager] invalid state transition', {
+                from: this._state,
+                to: target,
+                reason: result.reason,
+                sessionId: this._sessionId,
+            });
+            // Force to failed to avoid being stuck in an inconsistent state
+            this._state = 'failed';
+            return;
+        }
+        this._state = result.state;
+    }
+}

package/dist/_internal/platform/runtime/compaction/quality-score.d.ts

@@ -0,0 +1,70 @@
+/**
+ * quality-score.ts
+ *
+ * Compaction quality scoring — evaluates the output of a compaction strategy
+ * by combining compression ratio and semantic retention signals.
+ *
+ * Score range: 0.0 (worst) → 1.0 (best)
+ * Auto-switch threshold: scores below LOW_QUALITY_THRESHOLD trigger a strategy
+ * escalation to the next more-aggressive strategy.
+ */
+import type { StrategyInput, StrategyOutput, CompactionStrategy } from './types.js';
+/**
+ * Compaction runs scoring below this value are considered low-quality and
+ * trigger an automatic strategy switch.
+ */
+export declare const LOW_QUALITY_THRESHOLD = 0.4;
+/** Letter grade derived from the composite quality score. */
+export type CompactionQualityGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+/** Semantic retention signals evaluated during scoring. */
+export interface SemanticRetentionSignals {
+    /** At least one handoff/summary message is present in the output. */
+    hasHandoff: boolean;
+    /** Output contains non-trivial content (not just a blank handoff note). */
+    hasNonTrivialContent: boolean;
+    /** The output message count is a reasonable fraction of the input. */
+    messageCountSane: boolean;
+    /** The output token count is positive. */
+    positiveTokenCount: boolean;
+}
+/** Full quality score breakdown for a compaction run. */
+export interface CompactionQualityScore {
+    /** Fraction of tokens removed: (tokensBefore - tokensAfter) / tokensBefore. */
+    compressionRatio: number;
+    /** Normalised compression dimension score (0–1). */
+    compressionScore: number;
+    /** Semantic retention dimension score (0–1). */
+    retentionScore: number;
+    /** Composite quality score: weighted sum of compression + retention (0–1). */
+    score: number;
+    /** Letter grade derived from score. */
+    grade: CompactionQualityGrade;
+    /** Individual semantic retention signals. */
+    signals: SemanticRetentionSignals;
+    /** True when score < LOW_QUALITY_THRESHOLD and strategy escalation should occur. */
+    isLowQuality: boolean;
+    /** Human-readable description of the score for diagnostics. */
+    description: string;
+}
+/**
+ * Produces a human-readable diagnostic description for a quality score.
+ */
+export declare function describeScore(score: CompactionQualityScore): string;
+/**
+ * Computes the quality score with description filled in.
+ *
+ * Prefer this over `scoreCompactionOutput` for all public use.
+ */
+export declare function computeQualityScore(input: StrategyInput, output: StrategyOutput): CompactionQualityScore;
+/**
+ * Returns the next more-aggressive strategy for escalation when quality is low.
+ *
+ * Escalation path:
+ *   microcompact → autocompact → collapse → collapse (ceiling)
+ *   reactive     → reactive (already maximum)
+ *
+ * @param current - The strategy that produced the low-quality result.
+ * @returns The escalated strategy to re-run with.
+ */
+export declare function escalateStrategy(current: CompactionStrategy): CompactionStrategy;
+//# sourceMappingURL=quality-score.d.ts.map

package/dist/_internal/platform/runtime/compaction/quality-score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-score.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/compaction/quality-score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMpF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAkCzC,6DAA6D;AAC7D,MAAM,MAAM,sBAAsB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEjE,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,oBAAoB,EAAE,OAAO,CAAC;IAC9B,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,6CAA6C;IAC7C,OAAO,EAAE,wBAAwB,CAAC;IAClC,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACrB;AA+FD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAUnE;AA0CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,cAAc,GACrB,sBAAsB,CAKxB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,CAWhF"}