@hydraharness/harness-compaction 0.1.1-rc.10

package/lib/types/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Compaction Service Definition (`ctx.compaction`): providers decide when to
+ * compact and replace a history range with one summary node by subclassing
+ * {@link CompactionEngine}. This interface necessarily depends on session and LLM
+ * vocabulary; the rationale is in the
+ * [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+ * @module @hydraharness/harness-compaction
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import type { Session } from '@hydraharness/harness-session';
+import type { CommandId } from '@hydraharness/harness-commands/brand';
+import type { CompactionResult } from './types.ts';
+export type { CompactionResult } from './types.ts';
+export { CompactionId } from './brand.ts';
+export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts';
+export { compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts';
+export type { CompactionCheckpointSource } from './checkpoint.ts';
+/** Why automatic policy is asking a backend to consider compaction. */
+export type CompactionTrigger = 'pressure' | 'context-overflow';
+/** Expected failure classes for an explicit idle-session compaction request. */
+export type ManualCompactionErrorCode = 'busy' | 'cancelled' | 'changed' | 'summary' | 'commit' | 'persistence';
+/**
+ * Expected manual-compaction failure suitable for a direct human-command result.
+ * Shared durable-lock entry assertions may also throw the `busy` subtype from
+ * automatic compaction paths.
+ */
+export declare class ManualCompactionError extends Error {
+    readonly code: ManualCompactionErrorCode;
+    readonly name = "ManualCompactionError";
+    /**
+     * Create one classified compaction failure.
+     * @param code - stable failure class; `busy` may originate from any compaction entry path.
+     * @param message - backend diagnostic retained as the Error message.
+     * @param options - optional original failure.
+     */
+    constructor(code: ManualCompactionErrorCode, message: string, options?: ErrorOptions);
+}
+/** Minimal agent context compaction needs without depending on the agent package. */
+export interface CompactionAgentContext {
+    session: Session;
+    options: {
+        provider?: string;
+        model?: string;
+    };
+}
+/**
+ * Agent capability required to serialize an explicit idle-session compaction
+ * against driver turns. The durable `compaction/start` marker separately excludes
+ * other compaction transactions.
+ */
+export interface ManualCompactAgentContext extends CompactionAgentContext {
+    /**
+     * Run a non-turn maintenance operation only while the agent is idle, withholding later
+     * waking input until it settles.
+     * @param task - operation whose fulfillment or rejection is preserved, with an agent-owned cancellation signal.
+     * @throws synchronously when the agent is already active.
+     * @returns the task promise.
+     */
+    runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        compaction: CompactionEngine;
+    }
+}
+/**
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. The replacement user
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compaction`.
+ */
+export declare abstract class CompactionEngine extends Service {
+    constructor(ctx: Context);
+    /**
+     * Consider automatic compaction for one explicit trigger. Pressure policy
+     * uses the latest durable routed request, while context-overflow policy may
+     * force a useful balanced reduction even below the normal threshold. Return
+     * `null` when no safe range can be compacted. A single oversized retained
+     * unit or request envelope cannot be repaired through surface compaction.
+     *
+     * @param agent - agent context owning the session surface and routing options.
+     * @param trigger - normal pressure or provider-confirmed context overflow.
+     * @param signal - cancellation signal; model-backed implementations must forward it.
+     * @returns the compaction result, or `null` if no compaction was needed.
+     */
+    abstract compactIfNeeded(agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
+    /**
+     * Explicitly compact useful history even below automatic pressure thresholds.
+     * Implementations synchronously start an idle task before any asynchronous
+     * work, select a useful range without writing on a no-op, then
+     * append a standalone `compaction/start` before summarization. That durable
+     * marker is the compaction lock until one `compaction/end` attempt. Later waking
+     * prompts remain accepted in FIFO order and start only after the optional
+     * durability checkpoint and idle-task settlement. Context injected while the
+     * summary runs may sit between the marker pair; only the selected span must
+     * remain stable.
+     *
+     * @param agent - idle agent whose durable history should be compacted.
+     * @param signal - cancellation scoped to this compaction request.
+     * @param sourceCommandId - initiating command identity for a manual compaction.
+     * @returns the compaction result, or `null` when no safe useful range exists.
+     * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+     * changed-span, summarization/shrink, commit-stage, or persistence failures;
+     * an aborted request preserves its exact abort reason. Failed attempts remain
+     * visible in the log.
+     */
+    abstract compactNow(agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId): Promise<CompactionResult | null>;
+    /**
+     * Forcibly compact a range of surface nodes into a single summary node.
+     * `start` and `end` name an inclusive span by surface position, not numeric seq
+     * order; replacements can make visible seqs non-monotonic. Both edges must be
+     * balanced so assistant tool calls remain paired with their results. A model-
+     * backed implementation forwards cancellation and rejects active, missing,
+     * reversed, or unbalanced ranges. The target session is `agent.session`.
+     * Its replacement user message must use {@link compactCheckpointSource} with
+     * the transaction's `CompactionId`.
+     * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+     * for the edge checks.
+     *
+     * @param start - first surface seq, inclusive.
+     * @param end - last surface seq, inclusive.
+     * @param agent - context whose session is mutated and whose routing options guide summarization.
+     * @param signal - optional cancellation; model-backed implementations must forward it.
+     * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+     * @returns the appended event seqs, summary, replaced range, and token accounting.
+     */
+    abstract compactRegion(start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal): Promise<CompactionResult>;
+}
+export default CompactionEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,50 @@
+/**
+ * Compaction Service Definition (`ctx.compaction`): providers decide when to
+ * compact and replace a history range with one summary node by subclassing
+ * {@link CompactionEngine}. This interface necessarily depends on session and LLM
+ * vocabulary; the rationale is in the
+ * [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+ * @module @hydraharness/harness-compaction
+ */
+import { Service } from '@hydraharness/cordis';
+export { CompactionId } from "./brand.js";
+export { toolPairingBalancedAfter, toolPairingBalancedBefore } from "./tool-pairing.js";
+// The checkpoint source constructor and predicate are declared on the cordis-free
+// `./checkpoint` leaf so client and wire programs can name them without this
+// root's Context merge; the root stays the host-side entry point for both.
+export { compactCheckpointSource, isCompactCheckpointSource } from "./checkpoint.js";
+/**
+ * Expected manual-compaction failure suitable for a direct human-command result.
+ * Shared durable-lock entry assertions may also throw the `busy` subtype from
+ * automatic compaction paths.
+ */
+export class ManualCompactionError extends Error {
+    code;
+    name = 'ManualCompactionError';
+    /**
+     * Create one classified compaction failure.
+     * @param code - stable failure class; `busy` may originate from any compaction entry path.
+     * @param message - backend diagnostic retained as the Error message.
+     * @param options - optional original failure.
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. The replacement user
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compaction`.
+ */
+export class CompactionEngine extends Service {
+    constructor(ctx) {
+        super(ctx, 'compaction');
+    }
+}
+export default CompactionEngine;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned compaction log-stream invariants. @module @hydraharness/harness-compaction/invariant */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "compaction-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the compact invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,258 @@
+/** Package-owned compaction log-stream invariants. @module @hydraharness/harness-compaction/invariant */
+import { isReplacementSurfaceEvent } from '@hydraharness/harness-session';
+import { isCompactCheckpointSource } from "./checkpoint.js";
+const PACKAGE_NAME = '@hydraharness/harness-compaction';
+/** Cordis companion plugin name. */
+export const name = 'compaction-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Require a durable opaque identity to be a non-empty string. */
+function validateId(value, label, fail) {
+    if (typeof value !== 'string' || value.length === 0)
+        fail(`${label} must be a non-empty string`);
+}
+/** Keep the optional initiating command identity stable across one transaction. */
+function validateSourceCommandId(eventType, value, expected, fail) {
+    if (value !== undefined)
+        validateId(value, `${eventType} sourceCommandId`, fail);
+    if (value !== expected) {
+        fail(`${eventType} sourceCommandId ${String(value)} does not match compaction/start sourceCommandId ${String(expected)}`);
+    }
+}
+/** Validate one replacement checkpoint against its open compaction transaction. */
+function validateCheckpoint(trace, event, fail) {
+    const source = event.data.source;
+    validateId(source.compactionId, 'compaction checkpoint compactionId', fail);
+    if (source.sourceCommandId !== undefined) {
+        validateId(source.sourceCommandId, 'compaction checkpoint sourceCommandId', fail);
+    }
+    const open = trace.compaction;
+    if (open === undefined)
+        fail('compaction checkpoint has no matching compaction/start');
+    if (source.compactionId !== open.compactionId) {
+        fail(`compaction checkpoint id ${source.compactionId} does not match compaction/start id ${open.compactionId}`);
+    }
+    validateSourceCommandId('compaction checkpoint', source.sourceCommandId, open.sourceCommandId, fail);
+}
+/** Compaction starts still unmatched when a later seed boundary made them stale. */
+function inheritedOrphanStartSeqs(events) {
+    const stale = new Set();
+    let openStartSeq;
+    for (const event of events) {
+        if (event.type === 'compaction/start') {
+            openStartSeq = event.seq;
+        }
+        else if (event.type === 'compaction/end') {
+            openStartSeq = undefined;
+        }
+        else if (event.type === 'session/end-seed') {
+            if (openStartSeq !== undefined)
+                stale.add(openStartSeq);
+            openStartSeq = undefined;
+        }
+    }
+    return stale;
+}
+/** Keep every live compaction bracket on one side of each turn boundary. */
+function validateTurnBoundary(trace, event, fail) {
+    if ((event.type !== 'turn/start' && event.type !== 'turn/end')
+        || trace.compaction === undefined)
+        return;
+    const owner = trace.compaction.turn === null
+        ? 'standalone compaction'
+        : `compaction for turn ${trace.compaction.turn}`;
+    fail(`${event.type} cannot cross an open ${owner}`);
+}
+/** Advance the committed turn cursor after its boundary has been accepted. */
+function applyTurnBoundary(trace, event) {
+    if (event.type === 'turn/start') {
+        trace.openTurn = event.data.turn;
+        return true;
+    }
+    if (event.type === 'turn/end') {
+        trace.openTurn = null;
+        return true;
+    }
+    return false;
+}
+/** Require a numbered bracket inside its exact turn, or a standalone bracket between turns. */
+function validateOwner(owner, openTurn, eventType, fail) {
+    if (owner === null) {
+        if (openTurn !== null)
+            fail(`${eventType} is standalone but turn ${openTurn} is open`);
+        return;
+    }
+    if (openTurn === null)
+        fail(`${eventType} for turn ${owner} appended outside any open turn`);
+    if (owner !== openTurn)
+        fail(`${eventType} names turn ${owner} but open turn is ${openTurn}`);
+}
+/** Validate one compaction event without advancing committed trace state. */
+function validateCompactionEvent(trace, event, fail) {
+    if (event.type === 'session/end-seed')
+        return { kind: 'end-seed' };
+    if (event.type === 'user/message'
+        && isReplacementSurfaceEvent(event)
+        && isCompactCheckpointSource(event.data.source)) {
+        validateCheckpoint(trace, event, fail);
+        return undefined;
+    }
+    if (event.type !== 'compaction/start' && event.type !== 'compaction/summary' && event.type !== 'compaction/end') {
+        return undefined;
+    }
+    const open = trace.compaction;
+    if (event.type === 'compaction/start') {
+        validateId(event.data.compactionId, 'compaction/start compactionId', fail);
+        if (event.data.sourceCommandId !== undefined) {
+            validateId(event.data.sourceCommandId, 'compaction/start sourceCommandId', fail);
+        }
+        if (open !== undefined) {
+            const owner = open.turn === null ? 'standalone compaction' : `turn ${open.turn}`;
+            fail(`compaction/start while ${owner} is still compacting`);
+        }
+        validateOwner(event.data.turn, trace.openTurn, event.type, fail);
+        return {
+            kind: 'start',
+            compactionId: event.data.compactionId,
+            sourceCommandId: event.data.sourceCommandId,
+            startSeq: event.seq,
+            turn: event.data.turn,
+        };
+    }
+    if (event.type === 'compaction/summary') {
+        validateId(event.data.compactionId, 'compaction/summary compactionId', fail);
+        if (event.data.sourceCommandId !== undefined) {
+            validateId(event.data.sourceCommandId, 'compaction/summary sourceCommandId', fail);
+        }
+        if (open === undefined)
+            fail('compaction/summary has no matching compaction/start');
+        if (event.data.compactionId !== open.compactionId) {
+            fail(`compaction/summary id ${event.data.compactionId} does not match compaction/start id ${open.compactionId}`);
+        }
+        validateSourceCommandId('compaction/summary', event.data.sourceCommandId, open.sourceCommandId, fail);
+        validateOwner(open.turn, trace.openTurn, event.type, fail);
+        if (open.summarized)
+            fail('compaction/summary repeated within one compaction');
+        const seqs = event.data.shadowedSeqs;
+        if (seqs.length === 0)
+            fail('compaction/summary shadowedSeqs must be non-empty');
+        if (seqs[0] !== event.data.shadowedRange.start || seqs.at(-1) !== event.data.shadowedRange.end) {
+            fail('compaction/summary shadowedRange must match the first and last shadowedSeqs');
+        }
+        if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
+            fail('compaction/summary shadowedTokenCount must be a non-negative safe integer');
+        }
+        return {
+            kind: 'summary',
+            compactionId: open.compactionId,
+            sourceCommandId: open.sourceCommandId,
+            startSeq: open.startSeq,
+            turn: open.turn,
+        };
+    }
+    validateId(event.data.compactionId, 'compaction/end compactionId', fail);
+    if (event.data.sourceCommandId !== undefined) {
+        validateId(event.data.sourceCommandId, 'compaction/end sourceCommandId', fail);
+    }
+    if (open === undefined)
+        fail('compaction/end has no matching compaction/start');
+    if (event.data.compactionId !== open.compactionId) {
+        fail(`compaction/end id ${event.data.compactionId} does not match compaction/start id ${open.compactionId}`);
+    }
+    validateSourceCommandId('compaction/end', event.data.sourceCommandId, open.sourceCommandId, fail);
+    if (event.data.turn !== open.turn) {
+        fail(`compaction/end owner ${String(event.data.turn)} does not match compaction/start owner ${String(open.turn)}`);
+    }
+    validateOwner(open.turn, trace.openTurn, event.type, fail);
+    if (event.data.error === undefined && !open.summarized) {
+        fail('successful compaction/end requires one compaction/summary');
+    }
+    return { kind: 'end' };
+}
+/** Apply one committed compaction transition. */
+function applyCompactionTransition(transition) {
+    if (transition.kind === 'start') {
+        return {
+            compactionId: transition.compactionId,
+            sourceCommandId: transition.sourceCommandId,
+            startSeq: transition.startSeq,
+            turn: transition.turn,
+            summarized: false,
+        };
+    }
+    if (transition.kind === 'summary') {
+        return {
+            compactionId: transition.compactionId,
+            sourceCommandId: transition.sourceCommandId,
+            startSeq: transition.startSeq,
+            turn: transition.turn,
+            summarized: true,
+        };
+    }
+    return undefined;
+}
+/** Install compaction start/summary/end checks. */
+// Event owners keep precommit staging local so their vocabularies never move into a central helper.
+/* jscpd:ignore-start */
+const install = Object.assign((ctx, fail) => {
+    const traces = new WeakMap();
+    const staged = new WeakMap();
+    const seed = (session) => {
+        const trace = { openTurn: null, compaction: undefined };
+        traces.set(session, trace);
+        const staleOrphanStartSeqs = inheritedOrphanStartSeqs(session.events);
+        for (const event of session.events) {
+            // Constructor-seed repair boundaries can precede the end-seed marker
+            // that proves an inherited orphan stale. Replay that inherited prefix
+            // without letting the soon-to-be-cleared bracket veto its repair.
+            if (trace.compaction === undefined
+                || !staleOrphanStartSeqs.has(trace.compaction.startSeq)) {
+                validateTurnBoundary(trace, event, fail);
+            }
+            const transition = validateCompactionEvent(trace, event, fail);
+            if (transition !== undefined)
+                trace.compaction = applyCompactionTransition(transition);
+            applyTurnBoundary(trace, event);
+        }
+        return trace;
+    };
+    const traceFor = (session) => traces.get(session) ?? seed(session);
+    for (const session of ctx.sessions.list())
+        seed(session);
+    ctx.on('session/created', (session) => { seed(session); }, { global: true });
+    ctx.on('session/event', (session, event) => {
+        const trace = traceFor(session);
+        validateTurnBoundary(trace, event, fail);
+        if (applyTurnBoundary(trace, event))
+            return;
+        if (event.type !== 'session/end-seed'
+            && event.type !== 'compaction/start'
+            && event.type !== 'compaction/summary'
+            && event.type !== 'compaction/end')
+            return;
+        const candidate = staged.get(event);
+        /* v8 ignore next -- internal/dispatch stages every compaction event */
+        if (candidate === undefined || candidate.session !== session)
+            return fail('compaction event published without pre-commit validation');
+        staged.delete(event);
+        trace.compaction = applyCompactionTransition(candidate.transition);
+    }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        const trace = traceFor(session);
+        validateTurnBoundary(trace, event, fail);
+        const transition = validateCompactionEvent(trace, event, fail);
+        if (transition !== undefined)
+            staged.set(event, { session, transition });
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register the compact invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/tool-pairing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tool-pairing balance over a session surface. Compaction changes surface
+ * positions, so safe cuts are derived from tool-call/result content in current
+ * surface order rather than step markers.
+ * @module @hydraharness/harness-compaction/tool-pairing
+ */
+import type { Session } from '@hydraharness/harness-session';
+/**
+ * Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose leading cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export declare function toolPairingBalancedBefore(session: Session, seq: number): boolean;
+/**
+ * Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose trailing cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export declare function toolPairingBalancedAfter(session: Session, seq: number): boolean;
+//# sourceMappingURL=tool-pairing.d.ts.map

package/lib/types/tool-pairing.js

@@ -0,0 +1,101 @@
+/**
+ * Tool-pairing balance over a session surface. Compaction changes surface
+ * positions, so safe cuts are derived from tool-call/result content in current
+ * surface order rather than step markers.
+ * @module @hydraharness/harness-compaction/tool-pairing
+ */
+const balanceCacheBySession = new WeakMap();
+/** Return how one surface event changes the in-progress tool-call count. */
+function eventDelta(event) {
+    switch (event.type) {
+        case 'assistant/message':
+            return event.data.message.content.filter(block => block.type === 'tool-call').length;
+        case 'tool/result':
+            return -1;
+        default:
+            return 0;
+    }
+}
+/** Read and validate the event named by a surface sequence. */
+function eventForSeq(events, seq) {
+    const event = events[seq];
+    if (event === undefined || event.seq !== seq) {
+        throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`);
+    }
+    return event;
+}
+/** Fold surface sequences not yet in the cache into its balance state. */
+function extendCache(session, cache, seqs) {
+    const processed = cache.cutBalanced.length - 1;
+    const tail = seqs.slice(processed);
+    // Validate the unseen tail before mutating the live cache, so a corrupt
+    // append cannot leave a partially advanced state behind.
+    const events = session.events;
+    const pendingCuts = [];
+    let inProgressToolCalls = cache.inProgressToolCalls;
+    for (const seq of tail) {
+        inProgressToolCalls += eventDelta(eventForSeq(events, seq));
+        if (inProgressToolCalls < 0) {
+            throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`);
+        }
+        pendingCuts.push(inProgressToolCalls === 0);
+    }
+    tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset));
+    cache.cutBalanced = cache.cutBalanced.concat(pendingCuts);
+    cache.inProgressToolCalls = inProgressToolCalls;
+    return cache;
+}
+/** Return balance state synchronized with the current session surface. */
+function balanceCache(session) {
+    const surface = session.surface;
+    const seqs = surface.nodes;
+    const generation = surface.replaceGeneration;
+    const cached = balanceCacheBySession.get(session);
+    if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
+        // A rebuild is the same fold started from the empty-surface state, whose
+        // single leading cut is trivially balanced.
+        const rebuilt = extendCache(session, {
+            generation,
+            cutBalanced: [true],
+            indexBySeq: new Map(),
+            inProgressToolCalls: 0,
+        }, seqs);
+        balanceCacheBySession.set(session, rebuilt);
+        return rebuilt;
+    }
+    if (cached.cutBalanced.length - 1 < seqs.length)
+        return extendCache(session, cached, seqs);
+    return cached;
+}
+/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
+function cutBalance(cache, seq, offset) {
+    const index = cache.indexBySeq.get(seq);
+    const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset];
+    if (balanced === undefined) {
+        throw new Error(`tool-pairing balance: surface seq ${seq} not found`);
+    }
+    return balanced;
+}
+/**
+ * Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose leading cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export function toolPairingBalancedBefore(session, seq) {
+    return cutBalance(balanceCache(session), seq, 0);
+}
+/**
+ * Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose trailing cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export function toolPairingBalancedAfter(session, seq) {
+    return cutBalance(balanceCache(session), seq, 1);
+}
+//# sourceMappingURL=tool-pairing.js.map