@iworkforces/tracelattice 2.0.3

package/dist/contracts/interfaces.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Shared interface contracts for dependency injection.
+ *
+ * This module centralizes all cross-module interface definitions so that
+ * the DI container (ServiceRegistry) and other modules can depend on
+ * interfaces rather than concrete implementations.
+ *
+ * By importing from contracts/ instead of individual module files,
+ * we reduce lateral coupling and keep the dependency graph shallow.
+ *
+ * @module contracts
+ */
+import type { Edge } from '../core/graph/Edge.js';
+import type { EdgeId, SessionId, ThoughtId } from './ids.js';
+import type { ThoughtType } from './reasoning-types.js';
+/**
+ * Metrics interface for observability.
+ *
+ * Defines the contract for metrics collection used across modules.
+ * Implementations include the Prometheus-compatible Metrics class.
+ */
+export interface IMetrics {
+    counter(name: string, value?: number, labels?: Record<string, string>, help?: string): void;
+    gauge(name: string, value: number, labels?: Record<string, string>, help?: string): void;
+    histogram(name: string, value: number, labels?: Record<string, string>, buckets?: number[]): void;
+    get(name: string, labels?: Record<string, string>): number | undefined;
+    inc(name: string, labels?: Record<string, string>): void;
+    dec(name: string, labels?: Record<string, string>): void;
+    reset(): void;
+    export(): string;
+}
+/**
+ * Discovery cache interface for caching tool/skill discovery results.
+ *
+ * Defines the contract for LRU+TTL caching used by registries.
+ * Implementations include the DiscoveryCache class.
+ *
+ * @template T - The type of data being cached
+ */
+export interface IDiscoveryCache<T> {
+    get(key: string): T[] | null;
+    set(key: string, data: T[]): void;
+    has(key: string): boolean;
+    invalidate(key: string): void;
+    clear(): void;
+    dispose(): void;
+    size(): number;
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+}
+/**
+ * Configuration options for creating a discovery cache.
+ */
+export interface DiscoveryCacheOptions {
+    maxSize?: number;
+    ttl?: number;
+    cleanupInterval?: number;
+    metrics?: IMetrics;
+}
+/**
+ * Outcome recording interface for calibration data collection.
+ *
+ * Captures verification outcomes (predicted vs actual) to enable
+ * confidence calibration (Brier score, ECE) in later phases.
+ */
+export interface VerificationOutcome {
+    /** The thought id that made the prediction. */
+    thoughtId: ThoughtId;
+    /** The thought number of the prediction (backward compat). */
+    thoughtNumber: number;
+    /** The session this outcome belongs to. */
+    sessionId: SessionId;
+    /** The predicted confidence (0-1). */
+    predicted: number;
+    /** The actual outcome (0 = wrong, 1 = correct). */
+    actual: 0 | 1;
+    /** The thought type that made the prediction. */
+    type: ThoughtType;
+    /** Timestamp of outcome recording. */
+    recordedAt: number;
+}
+/**
+ * Interface for recording verification outcomes for calibration.
+ *
+ * Implementation is no-op when feature flags disable outcome recording.
+ * Enabled outcomes feed into the Calibrator (Phase 1 Wave A.3) for
+ * Brier score and ECE computation.
+ */
+export interface IOutcomeRecorder {
+    /**
+     * Assert that a target has not already received an outcome in this session.
+     * This preflight is side-effect free and a no-op when recording is disabled.
+     */
+    assertCanRecord(sessionId: SessionId, thoughtId: ThoughtId): void;
+    /**
+     * Record a verification outcome.
+     * No-op when outcome recording is disabled.
+     */
+    recordVerification(outcome: Omit<VerificationOutcome, 'recordedAt'>): void;
+    /**
+     * Get all recorded outcomes for a session.
+     * Returns empty array when disabled or no outcomes recorded.
+     */
+    getOutcomes(sessionId: SessionId): VerificationOutcome[];
+    /**
+     * Get outcomes across all sessions.
+     * Returns empty array when disabled.
+     */
+    getAllOutcomes(): VerificationOutcome[];
+    /**
+     * Clear outcomes for a specific session.
+     */
+    clearOutcomes(sessionId: SessionId): void;
+    /**
+     * Discard outcomes from every session namespace.
+     * Use only for a trusted process-wide reset; scoped callers must use `clearOutcomes`.
+     */
+    clearAllOutcomes(): void;
+    /**
+     * Whether outcome recording is currently enabled.
+     */
+    readonly enabled: boolean;
+}
+/**
+ * Edge store interface for managing directed acyclic graph edges.
+ *
+ * Stores relationships between thoughts as typed directed edges.
+ * Each edge connects two thoughts (by their `id` field) with a semantic
+ * relationship kind that drives reasoning controller decisions.
+ *
+ * Implementations must provide per-session isolation — edges in one
+ * session are invisible to another.
+ *
+ * @example
+ * ```typescript
+ * const store: IEdgeStore = new EdgeStore();
+ * store.addEdge({ id: 'abc', from: 'thought-1', to: 'thought-2', kind: 'sequence', sessionId: 's1', createdAt: Date.now() });
+ * const edges = store.outgoing('s1', 'thought-1');
+ * ```
+ */
+export interface IEdgeStore {
+    /**
+     * Add a directed edge to the store.
+     * Rejects self-edges (from === to) by throwing InvalidEdgeError.
+     * Deduplicates identical (from, to, kind, sessionId) tuples silently.
+     *
+     * @param edge - The edge to add
+     * @throws {InvalidEdgeError} When from === to
+     */
+    addEdge(edge: Edge): void;
+    /**
+     * Retrieve a specific edge by its id.
+     *
+     * @param id - The edge's unique identifier
+     * @returns The edge, or undefined if not found
+     */
+    getEdge(id: EdgeId): Edge | undefined;
+    /**
+     * Get all outgoing edges from a thought, sorted by createdAt ascending.
+     *
+     * @param sessionId - Session to query within
+     * @param from - Source thought id
+     * @returns Array of outgoing edges (may be empty)
+     */
+    outgoing(sessionId: SessionId, from: ThoughtId): readonly Edge[];
+    /**
+     * Get all incoming edges to a thought, sorted by createdAt ascending.
+     *
+     * @param sessionId - Session to query within
+     * @param to - Target thought id
+     * @returns Array of incoming edges (may be empty)
+     */
+    incoming(sessionId: SessionId, to: ThoughtId): readonly Edge[];
+    /**
+     * Get all edges in a session.
+     *
+     * @param sessionId - Session to query
+     * @returns All edges in the session (may be empty)
+     */
+    edgesForSession(sessionId: SessionId): readonly Edge[];
+    /**
+     * Remove unless both endpoints are retained; leave other sessions untouched and delete empty containers.
+     * @param sessionId - Session whose edges should be pruned
+     * @param retainedThoughtIds - Union of all retained thought ids in the session
+     * @returns The exact number of removed edges
+     */
+    pruneSession(sessionId: SessionId, retainedThoughtIds: ReadonlySet<ThoughtId>, retainedBranchThoughtIds?: ReadonlySet<ThoughtId>): number;
+    /**
+     * Clear all edges for a specific session.
+     * Other sessions are unaffected.
+     *
+     * @param sessionId - Session to clear
+     */
+    clearSession(sessionId: SessionId): void;
+    /**
+     * Discard edges from every session namespace.
+     * Use only for a trusted process-wide reset; scoped callers must use `clearSession`.
+     */
+    clearAll(): void;
+    /**
+     * Count edges.
+     *
+     * @param sessionId - If provided, count for that session only
+     * @returns Total edge count (across all sessions if no sessionId provided)
+     */
+    size(sessionId?: SessionId): number;
+}
+/**
+ * Tool registry interface used for tool_name allowlisting in ThoughtProcessor.
+ *
+ * Provides the minimal read-only contract needed to validate tool_call thoughts.
+ * Implementations include the concrete `ToolRegistry` class.
+ */
+export interface IToolRegistry {
+    /**
+     * Returns true if a tool with the given name is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns the names of all registered tools.
+     */
+    list(): string[];
+}
+/**
+ * Per-session async lock used to serialize state-mutating operations.
+ *
+ * Implementations must guarantee:
+ * - Concurrent calls for the same session id are serialized in arrival order.
+ * - Calls for different session ids never block each other.
+ * - The lock is always released, even when the critical section throws.
+ * - A waiter that times out does not corrupt the chain — later waiters
+ *   still observe correct serialization.
+ *
+ * Used by `ThoughtProcessor.process()` to prevent `reset_state` from
+ * interleaving with concurrent `addThought` calls for the same session.
+ */
+export interface ISessionLock {
+    /**
+     * Execute `fn` while holding the lock for the given session.
+     *
+     * @param sessionId - Session to lock (`undefined` shares a global slot).
+     * @param fn - Critical section to run while holding the lock.
+     * @param timeoutMs - Max wait for lock acquisition (default 5000ms).
+     * @throws {LockTimeoutError} If the lock is not acquired before `timeoutMs`.
+     */
+    withLock<T>(sessionId: SessionId | undefined, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+    /** Whether the session currently has a holder or queued operation. */
+    isActive(sessionId: SessionId | undefined): boolean;
+    /** Number of currently held lock chains (diagnostics). */
+    readonly size: number;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/contracts/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/contracts/interfaces.ts"],"names":[],"mappings":"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"}

package/dist/contracts/interfaces.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/persistence-work.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Attributable work contracts for buffered persistence generations.
+ *
+ * @module contracts/persistence-work
+ */
+import type { Summary } from '../core/compression/Summary.js';
+import type { Edge } from '../core/graph/Edge.js';
+import type { ThoughtData } from '../core/thought.js';
+import type { BranchId, SessionId } from './ids.js';
+/** Stable queue-assigned identity for one accepted persistence unit. */
+export type PersistenceWorkToken = string;
+/**
+ * One accepted persistence unit.
+ *
+ * Every variant has an explicit session, including global work attributed to
+ * `GLOBAL_SESSION_ID`. Snapshot variants use `key` and `version` for
+ * compare-and-set acknowledgement of the exact accepted snapshot.
+ */
+export type PersistenceWork = {
+    readonly kind: 'thought';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly thought: ThoughtData;
+} | {
+    readonly kind: 'branch';
+    readonly operation: 'save';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: BranchId;
+    readonly version: number;
+    readonly snapshot: readonly ThoughtData[];
+} | {
+    readonly kind: 'branch';
+    readonly operation: 'delete';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: BranchId;
+    readonly version: number;
+} | {
+    readonly kind: 'edge';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: SessionId;
+    readonly version: number;
+    readonly snapshot: readonly Edge[];
+} | {
+    readonly kind: 'summary';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: SessionId;
+    readonly version: number;
+    readonly snapshot: readonly Summary[];
+};
+/**
+ * Terminal failure for one accepted persistence unit.
+ *
+ * Snapshot failures retain their acknowledgement coordinates without exposing
+ * the persisted payload. `attempts` is the exact number of backend calls made.
+ */
+export type PersistenceWorkFailure = {
+    readonly kind: 'thought';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly attempts: number;
+    readonly cause: unknown;
+} | {
+    readonly kind: 'branch';
+    readonly operation: 'save' | 'delete';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: BranchId;
+    readonly version: number;
+    readonly attempts: number;
+    readonly cause: unknown;
+} | {
+    readonly kind: 'edge';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: SessionId;
+    readonly version: number;
+    readonly attempts: number;
+    readonly cause: unknown;
+} | {
+    readonly kind: 'summary';
+    readonly token: PersistenceWorkToken;
+    readonly sessionId: SessionId;
+    readonly key: SessionId;
+    readonly version: number;
+    readonly attempts: number;
+    readonly cause: unknown;
+};
+/** Immutable outcome captured when a persistence generation settles. */
+export type PersistenceGenerationResult = {
+    readonly failures: readonly PersistenceWorkFailure[];
+};
+//# sourceMappingURL=persistence-work.d.ts.map

package/dist/contracts/persistence-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-work.d.ts","sourceRoot":"","sources":["../../src/contracts/persistence-work.ts"],"names":[],"mappings":"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"}

package/dist/contracts/persistence-work.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/reasoning-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Classification of thought purpose — enables type-specific formatting, evaluation, and analytics.
+ *
+ * @example
+ * ```typescript
+ * const thoughtType: ThoughtType = 'hypothesis';
+ *
+ * // Use in conditional formatting
+ * if (thoughtType === 'verification') {
+ *   console.log('Verifying a hypothesis...');
+ * }
+ * ```
+ */
+export type ThoughtType = 'regular' | 'hypothesis' | 'verification' | 'critique' | 'synthesis' | 'meta' | 'tool_call' | 'tool_observation' | 'assumption' | 'decomposition' | 'backtrack';
+/**
+ * Machine-readable names for the 6 detected reasoning patterns.
+ *
+ * Each name corresponds to a private detector method in PatternDetector.
+ */
+export type PatternName = 'consecutive_without_verification' | 'unverified_hypothesis' | 'monotonic_type' | 'no_alternatives_explored' | 'confidence_drift' | 'healthy_verification';
+//# sourceMappingURL=reasoning-types.d.ts.map

package/dist/contracts/reasoning-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-types.d.ts","sourceRoot":"","sources":["../../src/contracts/reasoning-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACpB,SAAS,GACT,YAAY,GACZ,cAAc,GACd,UAAU,GACV,WAAW,GACX,MAAM,GACN,WAAW,GACX,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,WAAW,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACpB,kCAAkC,GAClC,uBAAuB,GACvB,gBAAgB,GAChB,0BAA0B,GAC1B,kBAAkB,GAClB,sBAAsB,CAAC"}

package/dist/contracts/reasoning-types.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/strategy.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Reasoning Strategy contract — defines how a strategy observes reasoning state
+ * and decides the next action (continue, branch, terminate, suspend).
+ *
+ * Strategies are pluggable policies that drive higher-level reasoning control
+ * flow on top of the sequential thinking pipeline. They are pure (no I/O) and
+ * receive a snapshot of session state via {@link StrategyContext}.
+ *
+ * @module contracts/strategy
+ */
+import type { SessionId } from './ids.js';
+import type { ThoughtData } from '../core/thought.js';
+import type { ReasoningStats } from '../core/reasoning.js';
+import type { GraphView } from '../core/graph/GraphView.js';
+/**
+ * Read-only snapshot of session state passed to a reasoning strategy.
+ *
+ * All fields are immutable references. Strategies MUST NOT mutate the
+ * history, graph, or stats — doing so will corrupt downstream consumers.
+ *
+ * @example
+ * ```ts
+ * const ctx: StrategyContext = {
+ *   sessionId: 'sess_42',
+ *   history: hm.getHistory('sess_42'),
+ *   graph: new GraphView(edgeStore, 'sess_42'),
+ *   stats: evaluator.computeStats(history),
+ *   currentThought: latestThought,
+ * };
+ * const decision = strategy.decide(ctx);
+ * ```
+ */
+export interface StrategyContext {
+    /** Session identifier this context belongs to. */
+    readonly sessionId: SessionId;
+    /** Chronological list of thoughts recorded in this session. */
+    readonly history: readonly ThoughtData[];
+    /** Read-only graph view for traversal (ancestors, descendants, etc.). Undefined when DAG edges are disabled. */
+    readonly graph: GraphView | undefined;
+    /** Aggregated reasoning analytics for the session. */
+    readonly stats: ReasoningStats;
+    /** The thought that just triggered the strategy decision. */
+    readonly currentThought: ThoughtData;
+}
+/**
+ * Discriminated union describing the action a strategy wants to take.
+ *
+ * - `continue`  — keep the current chain; optionally hint at next direction.
+ * - `branch`    — fork a new branch from a prior thought.
+ * - `terminate` — stop the reasoning chain; reason is required.
+ * - `suspend`   — pause the chain; may be resumed after `resumeAfter` ms.
+ *
+ * @example
+ * ```ts
+ * const d: StrategyDecision = { action: 'branch', branchId: 'alt-1', fromThought: 3 };
+ * if (d.action === 'branch') console.log(d.branchId);
+ * ```
+ */
+export type StrategyDecision = {
+    action: 'continue';
+    reason?: string;
+    nextHint?: string;
+} | {
+    action: 'branch';
+    branchId: string;
+    fromThought: number;
+    reason?: string;
+} | {
+    action: 'terminate';
+    reason: string;
+} | {
+    action: 'suspend';
+    reason: string;
+    resumeAfter?: number;
+};
+/**
+ * Pluggable reasoning strategy interface.
+ *
+ * Implementations are stateless with respect to global state — all input
+ * comes from the {@link StrategyContext}. Strategies are registered via DI
+ * and selected by name (e.g. `tot`, `cot`, `react`).
+ *
+ * @example
+ * ```ts
+ * class GreedyStrategy implements IReasoningStrategy {
+ *   readonly name = 'greedy';
+ *   decide(ctx: StrategyContext): StrategyDecision {
+ *     return { action: 'continue' };
+ *   }
+ *   shouldBranch(_ctx: StrategyContext): boolean { return false; }
+ *   shouldTerminate(ctx: StrategyContext): boolean {
+ *     return ctx.history.length >= 50;
+ *   }
+ * }
+ * ```
+ */
+export interface IReasoningStrategy {
+    /** Stable identifier (used for DI lookup and metrics labels). */
+    readonly name: string;
+    /** Compute the next action given the current state snapshot. */
+    decide(ctx: StrategyContext): StrategyDecision;
+    /** Predicate: should the chain branch right now? */
+    shouldBranch(ctx: StrategyContext): boolean;
+    /** Predicate: should the chain terminate right now? */
+    shouldTerminate(ctx: StrategyContext): boolean;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/contracts/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/contracts/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAG5D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,gHAAgH;IAChH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB,CAAC;IAC/C,oDAAoD;IACpD,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;IAC5C,uDAAuD;IACvD,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;CAC/C"}

package/dist/contracts/strategy.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/summary.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Summary store contract — defines the interface for persisting and querying
+ * compressed thought summaries produced by the compression subsystem.
+ *
+ * Implementations must provide per-session isolation: summaries from one
+ * session must never appear in queries scoped to another session.
+ *
+ * @module contracts/summary
+ */
+import type { Summary } from '../core/compression/Summary.js';
+import type { BranchId, SessionId, SummaryId } from './ids.js';
+export type { Summary };
+/**
+ * Storage and query contract for {@link Summary} records.
+ *
+ * Implementations are expected to be in-process (no I/O) and synchronous.
+ * Persistence backends may wrap this interface in async adapters.
+ *
+ * @example
+ * ```ts
+ * const store: ISummaryStore = new InMemorySummaryStore();
+ * store.add(summary);
+ * const all = store.forSession('sess_42');
+ * const branch = store.forBranch('sess_42', 'alt-1');
+ * ```
+ */
+export interface ISummaryStore {
+    /**
+     * Add a summary to the store.
+     *
+     * @param summary - The summary record to add
+     *
+     * @example
+     * ```ts
+     * store.add({ id: '01HX...', sessionId: 's1', rootThoughtId: 't5', ... });
+     * ```
+     */
+    add(summary: Summary): void;
+    /**
+     * Retrieve a summary by its unique id.
+     *
+     * @param id - The summary's unique identifier
+     * @returns The summary, or `undefined` if not found
+     *
+     * @example
+     * ```ts
+     * const s = store.get('01HX...');
+     * if (s) console.log(s.topics);
+     * ```
+     */
+    get(id: SummaryId): Summary | undefined;
+    /**
+     * Get all summaries for a session, in insertion order.
+     *
+     * @param sessionId - Session to query
+     * @returns Read-only array of summaries (may be empty)
+     *
+     * @example
+     * ```ts
+     * for (const s of store.forSession('sess_42')) {
+     *   console.log(s.coveredRange);
+     * }
+     * ```
+     */
+    forSession(sessionId: SessionId): readonly Summary[];
+    /**
+     * Get all summaries for a specific branch within a session.
+     *
+     * @param sessionId - Session to query
+     * @param branchId - Branch identifier to filter by
+     * @returns Read-only array of summaries on that branch (may be empty)
+     *
+     * @example
+     * ```ts
+     * const altSummaries = store.forBranch('sess_42', 'alt-1');
+     * ```
+     */
+    forBranch(sessionId: SessionId, branchId: BranchId): readonly Summary[];
+    /**
+     * Remove all summaries for a session. Other sessions are unaffected.
+     *
+     * @param sessionId - Session to clear
+     *
+     * @example
+     * ```ts
+     * store.clearSession('sess_42');
+     * ```
+     */
+    clearSession(sessionId: SessionId): void;
+    /**
+     * Discard summaries from every session namespace.
+     * Use only for a trusted process-wide reset; scoped callers must use `clearSession`.
+     */
+    clearAll(): void;
+    /**
+     * Count summaries.
+     *
+     * @param sessionId - If provided, count for that session only;
+     *   otherwise return the total across all sessions
+     * @returns The number of summaries
+     *
+     * @example
+     * ```ts
+     * const total = store.size();
+     * const perSession = store.size('sess_42');
+     * ```
+     */
+    size(sessionId?: SessionId): number;
+}
+//# sourceMappingURL=summary.d.ts.map

package/dist/contracts/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../src/contracts/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE/D,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;;OASG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAExC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CAAC;IAErD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,OAAO,EAAE,CAAC;IAExE;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzC;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACpC"}

package/dist/contracts/summary.js

@@ -0,0 +1 @@
+export { };