@hasna-internal/kai-session-query 0.1.1-rc.2

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-session-query`.
+* @module @hasna-internal/kai-session-query/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-session-query";
+/** Cordis companion plugin name. */
+const name = "session-query-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: query results are immutable per-call projections whose lineage and event
+* relations are validated while they are built; the service retains no observable result state.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/config.d.ts

@@ -0,0 +1,21 @@
+/** Public configuration and typed failures for the combined session-query service. */
+import { HarnessError } from '@hasna-internal/kai-llm';
+/** Default maximum `before`/`after` raw-event window. */
+export declare const SESSION_QUERY_READ_WINDOW_MAX = 50;
+/** Default maximum number of concurrent persisted-log inspections in one batch read. */
+export declare const SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY = 4;
+/** Backend-independent configuration inherited by every session-query implementation. */
+export interface Config {
+    /** Maximum accepted raw read context on either side. Defaults to 50. */
+    readWindowMax?: number;
+    /** Maximum concurrent persisted-log inspections in one batch read. Defaults to 4. */
+    persistedInspectConcurrency?: number;
+}
+/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
+export type SessionQueryErrorCode = 'SESSION_QUERY_ABORTED' | 'SESSION_QUERY_CORRUPT_SESSION' | 'SESSION_QUERY_EVENT_NOT_FOUND' | 'SESSION_QUERY_INDEX_FAILED' | 'SESSION_QUERY_INVALID_CONFIG' | 'SESSION_QUERY_INVALID_CURSOR' | 'SESSION_QUERY_INVALID_FILTER' | 'SESSION_QUERY_INVALID_LIMIT' | 'SESSION_QUERY_INVALID_QUERY' | 'SESSION_QUERY_INVALID_LINEAGE' | 'SESSION_QUERY_INVALID_SURFACE' | 'SESSION_QUERY_INVALID_WINDOW' | 'SESSION_QUERY_PERSISTENCE_FAILED' | 'SESSION_QUERY_SEARCH_DISABLED' | 'SESSION_QUERY_SESSION_NOT_FOUND' | 'SESSION_QUERY_STALE_CURSOR' | 'SESSION_QUERY_SOURCE_CONFLICT';
+/** Typed session-query failure whose `code` is one closed taxonomy member. */
+export declare class SessionQueryError extends HarnessError {
+    readonly code: SessionQueryErrorCode;
+    constructor(message: string, code: SessionQueryErrorCode, options?: ErrorOptions);
+}
+//# sourceMappingURL=config.d.ts.map

package/lib/types/corpus.d.ts

@@ -0,0 +1,64 @@
+/** Live/persisted logical-corpus resolution for session-query. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionHeader, SessionId } from '@hasna-internal/kai-session';
+import type { SessionRecord } from './types.ts';
+/** Detached source selected for one exact read. */
+export interface LogicalSession {
+    /** Cloned source header. */
+    header: SessionHeader;
+    /** Cloned raw event log. */
+    events: SessionEvent[];
+}
+/** Borrowed source visible only during one synchronous batch projection. */
+export interface LogicalSessionSource {
+    /** Header selected with `events`; callers must clone retained output. */
+    readonly header: SessionHeader;
+    /** Raw events selected with `header`; valid only for the projection call. */
+    readonly events: readonly SessionEvent[];
+}
+/** One source-projection result in a batch logical-corpus observation. */
+export type LogicalProjectionResult<Value> = {
+    sessionId: SessionId;
+    status: 'fulfilled';
+    value: Value;
+} | {
+    sessionId: SessionId;
+    status: 'rejected';
+    reason: unknown;
+};
+/** Resolves a live-preferred corpus against the persistence service mounted now. */
+export declare class SessionCorpus {
+    private readonly _ctx;
+    private readonly _persistedInspectConcurrency;
+    private _persistence;
+    private readonly _optionalPersistenceFiber;
+    constructor(_ctx: Context, _persistedInspectConcurrency: number);
+    /**
+     * List the complete logical corpus with live precedence and cloned headers.
+     * @param signal - optional cancellation for persistence listing.
+     * @returns records in deterministic newest-first order.
+     */
+    listSessions(signal?: AbortSignal): Promise<SessionRecord[]>;
+    /**
+     * Load one logical source, preferring a detached live snapshot.
+     *
+     * A known live target never consults persistence, so an optional backend's
+     * failure cannot make current in-memory history unreadable.
+     * @param sessionId - session to resolve.
+     * @param signal - optional cancellation for persisted source resolution.
+     * @returns detached live-preferred header and events.
+     */
+    load(sessionId: SessionId, signal?: AbortSignal): Promise<LogicalSession>;
+    /**
+     * Project unique logical sources immediately from one persistence listing.
+     *
+     * The synchronous projector runs before a persisted worker claims its next id.
+     * Full logs are borrowed only for that call and never retained by the batch.
+     * @param sessionIds - sessions to resolve in first-occurrence order.
+     * @param project - synchronous fold that owns/clones every retained value.
+     * @param signal - cancellation shared by listing and every persisted inspection.
+     * @returns one fulfilled or rejected projected result per unique requested id.
+     */
+    projectMany<Value>(sessionIds: readonly SessionId[], project: (source: LogicalSessionSource) => Value, signal?: AbortSignal): Promise<LogicalProjectionResult<Value>[]>;
+}
+//# sourceMappingURL=corpus.d.ts.map

package/lib/types/cursor.d.ts

@@ -0,0 +1,11 @@
+/** Opaque cursor identity for session-search pagination. */
+import type { Branded } from '@hasna-internal/kai-brand';
+/** Provider-owned opaque continuation token returned by session search. */
+export type SessionSearchCursor = Branded<'SessionSearchCursor'>;
+/**
+ * Brand an encoded provider cursor for the public search contract.
+ * @param value - opaque encoded cursor value.
+ * @returns the same runtime string with session-search cursor identity.
+ */
+export declare function SessionSearchCursor(value: string): SessionSearchCursor;
+//# sourceMappingURL=cursor.d.ts.map

package/lib/types/documents.d.ts

@@ -0,0 +1,18 @@
+/** Shared event metadata and semantic-document projection. */
+import type { SessionEvent, SessionId } from '@hasna-internal/kai-session';
+import type { SessionEventRecord, SessionEventSearchDocument } from './types.ts';
+/**
+ * Project a raw log into lightweight surface-aware event records.
+ * @param sessionId - session that owns the log.
+ * @param events - complete contiguous raw event log.
+ * @returns one record per event in ascending seq order.
+ */
+export declare function buildSessionEventRecords(sessionId: SessionId, events: readonly SessionEvent[]): SessionEventRecord[];
+/**
+ * Build first-party semantic documents for one complete raw event log.
+ * @param sessionId - session that owns the log.
+ * @param events - complete contiguous raw event log.
+ * @returns searchable documents in ascending seq order; structural events are omitted.
+ */
+export declare function buildSessionEventSearchDocuments(sessionId: SessionId, events: readonly SessionEvent[]): SessionEventSearchDocument[];
+//# sourceMappingURL=documents.d.ts.map

package/lib/types/extraction.d.ts

@@ -0,0 +1,12 @@
+/** First-party semantic text extraction for session-query consumers. */
+import type { SessionEvent } from '@hasna-internal/kai-session';
+/**
+ * Extract searchable semantic text from one first-party session event.
+ *
+ * Structural boundaries, raw stream chunks, request envelopes, and unknown
+ * declaration-merged events contribute no text.
+ * @param event - event to inspect.
+ * @returns newline-joined semantic text, or an empty string when non-searchable.
+ */
+export declare function extractSessionEventText(event: SessionEvent): string;
+//# sourceMappingURL=extraction.d.ts.map

package/lib/types/filters.d.ts

@@ -0,0 +1,35 @@
+/** Pure provider-independent predicates for logical sessions and event text. */
+import type { SessionEventResultFilter, SessionEventSearchDocument, SessionRecord, SessionResultFilter } from './types.ts';
+/**
+ * Apply ANDed logical-session filters while preserving input order.
+ * @param records - detached logical-session records to inspect.
+ * @param filters - clauses whose list values are ORed within each clause.
+ * @returns records accepted by every clause.
+ */
+export declare function filterSessionResults<T extends SessionRecord>(records: readonly T[], filters?: readonly SessionResultFilter[]): T[];
+/**
+ * Apply ANDed event filters to extracted semantic documents.
+ * @param documents - semantic documents produced by {@link buildSessionEventSearchDocuments}.
+ * @param filters - metadata and literal-text predicates.
+ * @returns documents accepted by every clause, in input order.
+ */
+export declare function filterSessionEventDocuments<T extends SessionEventSearchDocument>(documents: readonly T[], filters?: readonly SessionEventResultFilter[]): T[];
+/**
+ * Copy and validate logical-session filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export declare function materializeSessionResultFilters(filters: readonly SessionResultFilter[]): SessionResultFilter[];
+/**
+ * Copy and validate event filters before an asynchronous boundary.
+ * @param filters - caller-owned clauses to materialize.
+ * @returns detached validated clauses.
+ */
+export declare function materializeSessionEventResultFilters(filters: readonly SessionEventResultFilter[]): SessionEventResultFilter[];
+/**
+ * Compile a literal case-insensitive, whitespace-flexible semantic-text match.
+ * @param text - caller-provided literal text.
+ * @returns Unicode-aware regular expression safe from regex injection.
+ */
+export declare function compileSessionTextFilter(text: string): RegExp;
+//# sourceMappingURL=filters.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Service Definition for combined session-history reads, traces, filters, and full-text search.
+ *
+ * @module @hasna-internal/kai-session-query
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { type SessionId } from '@hasna-internal/kai-session';
+import type { SessionTitleSnapshot } from '@hasna-internal/kai-session-title';
+import type { SessionEventResultFilter, SessionEventSearchPage, SessionEventReadRequest, SessionEventRecord, SessionEventSearchDocument, SessionEventSearchRequest, SessionEventTraceObservation, SessionEventTraceRequest, SessionEventWindow, SessionLineageTrace, SessionLogSnapshot, SessionRecord, SessionResultFilter, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest, SessionSurfaceSnapshot, SessionTitleObservation, SessionTitleObservationResult } from './types.ts';
+import { type Config } from './config.ts';
+export type * from './types.ts';
+export { SessionSearchCursor } from './cursor.ts';
+export type { Config, SessionQueryErrorCode } from './config.ts';
+export { SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY, SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError, } from './config.ts';
+export { extractSessionEventText } from './extraction.ts';
+export { buildSessionEventRecords, buildSessionEventSearchDocuments } from './documents.ts';
+export { compileSessionTextFilter, filterSessionEventDocuments, filterSessionResults, materializeSessionEventResultFilters, materializeSessionResultFilters, } from './filters.ts';
+export { assertSessionHeadersCompatible } from './sources.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessionQuery: SessionQueryEngine;
+    }
+}
+/**
+ * Unified live-preferred session query service.
+ *
+ * Exact reads, filters, and traces are backend-independent concrete behavior.
+ * A backend implements full-text observation, reconciliation, ranking, cursor
+ * generations, and query execution on the same `ctx.sessionQuery` service.
+ */
+export declare abstract class SessionQueryEngine extends Service {
+    static inject: string[];
+    private readonly _readWindowMax;
+    private readonly _corpus;
+    constructor(ctx: Context, config?: Config);
+    /**
+     * Search the live-preferred logical corpus and group by session.
+     * @param request - query text, metadata filters, page size, and cursor.
+     * @param exec - optional cancellation control.
+     * @returns session hits ranked by their strongest matching event.
+     */
+    abstract searchSessions(request: SessionSearchRequest, exec?: SessionSearchExecContext): Promise<SessionSearchPage<SessionSearchHit>>;
+    /**
+     * Search events within one live-preferred logical session.
+     * @param request - target session, query text, filters, page size, and cursor.
+     * @param exec - optional cancellation control.
+     * @returns matching event hits and their target header from one indexed generation.
+     */
+    abstract searchEvents(request: SessionEventSearchRequest, exec?: SessionSearchExecContext): Promise<SessionEventSearchPage>;
+    /**
+     * List the complete logical corpus using live-preferred records.
+     * @param signal - optional cancellation for persistence listing.
+     * @returns deterministic newest-first cloned session records.
+     */
+    listSessions(signal?: AbortSignal): Promise<SessionRecord[]>;
+    /**
+     * Read and replay-validate one complete logical session log without making it live.
+     * @param sessionId - live or persisted session id to read.
+     * @returns cloned header and complete raw event log from one observation.
+     * @throws when persistence, header compatibility, or replay validation fails.
+     */
+    readSession(sessionId: SessionId): Promise<SessionLogSnapshot>;
+    /**
+     * Filter the complete logical corpus with provider-independent predicates.
+     * @param filters - ANDed session metadata and availability clauses.
+     * @param signal - optional cancellation for persistence listing.
+     * @returns matching cloned records in deterministic newest-first order.
+     */
+    filterSessions(filters: readonly SessionResultFilter[], signal?: AbortSignal): Promise<SessionRecord[]>;
+    /**
+     * Fold the latest log-backed title from one live-preferred logical session.
+     * @param sessionId - live or persisted session id to read.
+     * @param signal - optional cancellation for source resolution and title folding.
+     * @returns latest title snapshot, or `undefined` when the log has no title event.
+     */
+    readTitle(sessionId: SessionId, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>;
+    /**
+     * Fold the latest title and return its source header from one corpus observation.
+     * @param sessionId - live or persisted session id to read.
+     * @param signal - optional cancellation for source resolution and title folding.
+     * @returns cloned source header and optional latest title snapshot.
+     */
+    readTitleSnapshot(sessionId: SessionId, signal?: AbortSignal): Promise<SessionTitleObservation>;
+    /**
+     * Fold titles for unique sessions from one cancellable corpus observation.
+     *
+     * Results preserve first-occurrence input order. Operational failures stay
+     * isolated per session, while cancellation rejects the complete operation.
+     * @param sessionIds - live or persisted session ids to observe.
+     * @param signal - optional cancellation shared by all source reads.
+     * @returns one fulfilled or rejected result per unique requested id.
+     */
+    readTitleSnapshots(sessionIds: readonly SessionId[], signal?: AbortSignal): Promise<SessionTitleObservationResult[]>;
+    /**
+     * List lightweight raw-log event records for one logical session.
+     * @param sessionId - live-preferred session id to read.
+     * @returns event records in ascending seq order.
+     */
+    listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>;
+    /**
+     * Scan first-party semantic event documents with provider-independent filters.
+     * @param sessionId - live-preferred session id to scan.
+     * @param filters - ANDed metadata and literal-text predicates.
+     * @returns matching semantic documents in ascending seq order.
+     */
+    filterEvents(sessionId: SessionId, filters: readonly SessionEventResultFilter[]): Promise<SessionEventSearchDocument[]>;
+    private _filterSessions;
+    private _filterEvents;
+    /**
+     * Read one session's complete current model surface from one corpus observation.
+     * @param sessionId - live-preferred session id to read.
+     * @returns cloned header, current surface, and the last sequence number included in the raw-log capture.
+     * @throws when source resolution fails or the session surface is invalid.
+     */
+    readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>;
+    /**
+     * Trace known ancestry and descendants from one corpus observation.
+     * @param sessionId - logical session id to trace.
+     * @param signal - optional cancellation for persistence listing.
+     * @returns a complete lineage or the first parent that could not be resolved.
+     * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+     */
+    traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>;
+    /**
+     * Trace one event's direct positional replacements and cited source events.
+     * @param request - target session id and event seq.
+     * @param signal - optional cancellation for persisted source resolution.
+     * @returns source header, direct links, and the target's positional replacement chain.
+     * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
+     */
+    traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>;
+    /**
+     * Read one full event plus a bounded raw-log context window.
+     * @param request - target session/seq and context sizes.
+     * @param signal - optional cancellation for persisted source resolution.
+     * @returns cloned target and neighboring events.
+     */
+    readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>;
+    private _readEvent;
+    private _readWindow;
+}
+export default SessionQueryEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-session-query`.
+ * @module @hasna-internal/kai-session-query/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-query-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's 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/sources.d.ts

@@ -0,0 +1,9 @@
+/** Shared immutable-header checks for logical session source observers. */
+import type { SessionHeader } from '@hasna-internal/kai-session';
+/**
+ * Reject incompatible observations of one logical session source.
+ * @param a - first live, listed, or loaded header observation.
+ * @param b - second header observation expected to identify the same source.
+ */
+export declare function assertSessionHeadersCompatible(a: SessionHeader, b: SessionHeader): void;
+//# sourceMappingURL=sources.d.ts.map

package/lib/types/tracing.d.ts

@@ -0,0 +1,33 @@
+/** One-shot session-lineage and event-relationship tracing helpers. */
+import type { SessionEvent, SessionId, SurfaceEvent } from '@hasna-internal/kai-session';
+import type { SessionEventRecord, SessionEventTrace, SessionLineageTrace, SessionRecord } from './types.ts';
+/**
+ * Classify a raw event log with one canonical surface fold.
+ * @param sessionId - owner of the event log.
+ * @param events - detached raw event log.
+ * @returns lightweight records in ascending log order.
+ */
+export declare function eventRecords(sessionId: SessionId, events: readonly SessionEvent[]): SessionEventRecord[];
+/**
+ * Fold and return the current model surface after validating the whole log.
+ * @param sessionId - owner used in query diagnostics.
+ * @param events - detached raw event log from one corpus observation.
+ * @returns detached current surface events in folded order.
+ */
+export declare function currentSurfaceEvents(sessionId: SessionId, events: readonly SessionEvent[]): SurfaceEvent[];
+/**
+ * Trace one target after one canonical surface fold and whole-log validation.
+ * @param sessionId - owner of the event log.
+ * @param events - detached raw event log.
+ * @param seq - target event seq.
+ * @returns direct surface replacements and relationships to cited source events.
+ */
+export declare function traceEvent(sessionId: SessionId, events: readonly SessionEvent[], seq: number): SessionEventTrace;
+/**
+ * Trace one target's known ancestry and recursively known descendants.
+ * @param records - complete logical corpus from one observation.
+ * @param sessionId - target session id.
+ * @returns complete or explicitly partial lineage.
+ */
+export declare function traceSession(records: readonly SessionRecord[], sessionId: SessionId): SessionLineageTrace;
+//# sourceMappingURL=tracing.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Public records for exact reads and relationship traces over the
+ * live-preferred logical session corpus.
+ *
+ * @module @hasna-internal/kai-session-query/types
+ */
+import type { SessionEvent, SessionEventType, SessionHeader, SessionId, SurfaceEvent } from '@hasna-internal/kai-session';
+import type { SessionTitleSnapshot } from '@hasna-internal/kai-session-title';
+import type { SessionSearchCursor } from './cursor.ts';
+export type { SessionSearchCursor } from './cursor.ts';
+/** Whether an event is current model context, replaced context, or raw-log-only. */
+export type SessionEventSurface = 'current' | 'shadowed' | 'log-only';
+/** Lightweight identity and source availability for one logical session. */
+export interface SessionRecord {
+    /** Cloned session header selected from the live-preferred corpus. */
+    header: SessionHeader;
+    /** Whether the id currently exists in `ctx.sessions`. */
+    live: boolean;
+    /** Whether the active persistence backend currently materializes the id. */
+    persisted: boolean;
+}
+/** One atomic live-preferred observation of a session's current model surface. */
+export interface SessionSurfaceSnapshot {
+    /** Cloned session header selected from the same corpus observation as `events`. */
+    session: SessionHeader;
+    /** Highest raw-log seq included in the observation, or `null` for an empty log. */
+    capturedThroughSeq: number | null;
+    /** Cloned current surface events in model-history order. */
+    events: SurfaceEvent[];
+}
+/** One validated detached observation of a logical session's complete raw log. */
+export interface SessionLogSnapshot {
+    /** Cloned session header selected from the same observation as `events`. */
+    session: SessionHeader;
+    /** Cloned contiguous raw events after persistence repair and replay validation. */
+    events: SessionEvent[];
+}
+/** Lightweight metadata for one event within a logical session. */
+export interface SessionEventRecord {
+    /** Session that owns the event. */
+    sessionId: SessionId;
+    /** Monotonic event seq within the session. */
+    seq: number;
+    /** Discriminant of the session event. */
+    type: SessionEventType;
+    /** Event timestamp in Unix epoch milliseconds. */
+    time: number;
+    /** Event placement in the folded session surface. */
+    surface: SessionEventSurface;
+}
+/** Recursive descendant node in a session-lineage trace. */
+export interface SessionLineageNode {
+    /** Detached logical-corpus record for this descendant. */
+    session: SessionRecord;
+    /** Direct children, each carrying its own recursive descendants. */
+    descendants: SessionLineageNode[];
+}
+/** Known ancestry and descendants for one logical session. */
+export type SessionLineageTrace = {
+    /** Detached record for the session that was traced. */
+    target: SessionRecord;
+    /** Known parents from the immediate parent outward. */
+    ancestors: SessionRecord[];
+    /** Complete known descendant trees rooted at the target's direct children. */
+    descendants: SessionLineageNode[];
+} & ({
+    /** The complete parent chain is present in the logical corpus. */
+    complete: true;
+    /** Detached record at the top of the complete lineage. */
+    root: SessionRecord;
+} | {
+    /** The parent chain leaves the visible logical corpus. */
+    complete: false;
+    /** First parent id that is not present in the logical corpus. */
+    unresolvedParentId: SessionId;
+});
+/** Request for direct surface replacements and relationships to cited source events around one event. */
+export interface SessionEventTraceRequest {
+    /** Session that owns the target event. */
+    sessionId: SessionId;
+    /** Target event seq. */
+    seq: number;
+}
+/** Direct surface replacements and relationships to cited source events for one event. */
+export interface SessionEventTrace {
+    /** Lightweight target record. */
+    target: SessionEventRecord;
+    /** Immediate positional replacement event, when the target was shadowed. */
+    replacedBy?: number;
+    /** Positional replacers from the immediate replacement to the final replacement. */
+    replacementChain: number[];
+    /** Surface nodes directly removed when the target itself performed a replacement. */
+    replacedEventSeqs: number[];
+    /** Earlier events cited directly as sources, in their recorded order. */
+    sourceEventSeqs: number[];
+    /** Later events that directly cite the target as a source, in log order. */
+    derivedEventSeqs: number[];
+}
+/** Event relationships bound to the same session-header observation. */
+export interface SessionEventTraceObservation extends SessionEventTrace {
+    /** Cloned header selected with the event log used for the trace. */
+    session: SessionHeader;
+}
+/** Request for one event plus raw neighboring log context. */
+export interface SessionEventReadRequest {
+    /** Session that owns the target event. */
+    sessionId: SessionId;
+    /** Target event seq. */
+    seq: number;
+    /** Number of preceding raw events to include. */
+    before?: number;
+    /** Number of following raw events to include. */
+    after?: number;
+}
+/** Full target event and a bounded raw-log window. */
+export interface SessionEventWindow {
+    /** Cloned header for the live-preferred source read. */
+    session: SessionHeader;
+    /** Full cloned target event. */
+    target: SessionEvent;
+    /** Full cloned events from `startSeq` through `endSeq`. */
+    events: SessionEvent[];
+    /** First seq included in `events`. */
+    startSeq: number;
+    /** Last seq included in `events`. */
+    endSeq: number;
+}
+/** Latest folded title bound to the same session-header observation. */
+export interface SessionTitleObservation {
+    /** Cloned header selected with the event log used for the title fold. */
+    session: SessionHeader;
+    /** Latest title snapshot, absent when the observed log has no title. */
+    title?: SessionTitleSnapshot;
+}
+/** One ordered result from a batch title observation. */
+export type SessionTitleObservationResult = {
+    /** Requested session id. */
+    sessionId: SessionId;
+    /** Successful atomic header/title observation. */
+    status: 'fulfilled';
+    /** Header and optional latest title from one logical source. */
+    value: SessionTitleObservation;
+} | {
+    /** Requested session id. */
+    sessionId: SessionId;
+    /** Operational failure isolated to this session. */
+    status: 'rejected';
+    /** Original failure from logical-source resolution or title folding. */
+    reason: unknown;
+};
+/** Inclusive numeric interval used by time and sequence filters. */
+export interface SessionResultRange {
+    /** Inclusive lower bound. */
+    from?: number;
+    /** Inclusive upper bound. */
+    to?: number;
+}
+/** Source availability predicates understood by logical-session filters. */
+export type SessionAvailability = 'live' | 'persisted';
+/**
+ * One logical-session predicate. A filter array is ANDed; `values` within a
+ * clause are ORed.
+ */
+export type SessionResultFilter = {
+    kind: 'id';
+    values: readonly SessionId[];
+} | {
+    kind: 'cwd';
+    values: readonly (string | null)[];
+} | ({
+    kind: 'created-at';
+} & SessionResultRange) | {
+    kind: 'parent';
+    values: readonly (SessionId | null)[];
+} | {
+    kind: 'availability';
+    values: readonly SessionAvailability[];
+};
+/**
+ * One event predicate. A filter array is ANDed; list-valued clauses are ORed.
+ * Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
+ */
+export type SessionEventResultFilter = ({
+    kind: 'seq';
+} & SessionResultRange) | ({
+    kind: 'time';
+} & SessionResultRange) | {
+    kind: 'type';
+    values: readonly SessionEventType[];
+} | {
+    kind: 'surface';
+    values: readonly SessionEventSurface[];
+} | {
+    kind: 'text';
+    text: string;
+};
+/** Event predicates a full-text provider can apply before relevance ranking. */
+export type SessionEventMetadataFilter = Exclude<SessionEventResultFilter, {
+    kind: 'text';
+}>;
+/** Searchable semantic document derived from one session event. */
+export interface SessionEventSearchDocument extends SessionEventRecord {
+    /** First-party semantic text used by scan filters and full-text indexes. */
+    text: string;
+}
+/** One cursor-paginated result page. */
+export interface SessionSearchPage<T> {
+    /** Results for this page in contract-defined order. */
+    items: readonly T[];
+    /** Opaque continuation cursor, absent on the final page. */
+    nextCursor?: SessionSearchCursor;
+}
+/** Event-search results bound to the indexed target-session observation. */
+export interface SessionEventSearchPage extends SessionSearchPage<SessionEventSearchHit> {
+    /** Cloned target header from the same indexed generation as `items`. */
+    session: SessionHeader;
+}
+/** Controls shared by cross-session and within-session search calls. */
+export interface SessionSearchExecContext {
+    /** Abort caller waiting and interrupt provider work where supported. */
+    signal?: AbortSignal;
+}
+/** Cross-session full-text search request. */
+export interface SessionSearchRequest {
+    /** Full-text query interpreted as data, never executable FTS syntax. */
+    query: string;
+    /** Logical-session predicates applied before event ranking. */
+    sessionFilters?: readonly SessionResultFilter[];
+    /** Event predicates applied before event ranking. */
+    eventFilters?: readonly SessionEventMetadataFilter[];
+    /** Maximum sessions in this page. */
+    limit?: number;
+    /** Opaque cursor returned for the identical normalized request. */
+    cursor?: SessionSearchCursor;
+}
+/** Within-session full-text search request. */
+export interface SessionEventSearchRequest {
+    /** Session whose live-preferred logical log is searched. */
+    sessionId: SessionId;
+    /** Full-text query interpreted as data, never executable FTS syntax. */
+    query: string;
+    /** Event predicates applied before ranking. */
+    filters?: readonly SessionEventMetadataFilter[];
+    /** Maximum events in this page. */
+    limit?: number;
+    /** Opaque cursor returned for the identical normalized request. */
+    cursor?: SessionSearchCursor;
+}
+/** One event full-text search hit with a bounded plain-text excerpt. */
+export interface SessionEventSearchHit extends SessionEventRecord {
+    /** Plain text excerpt selected around the match. */
+    snippet: string;
+}
+/** One grouped cross-session hit, ranked by its strongest matching event. */
+export interface SessionSearchHit extends SessionRecord {
+    /** Strongest matching event for this session. */
+    bestMatch: SessionEventSearchHit;
+}
+//# sourceMappingURL=types.d.ts.map