@x1a0f3n9/dsh-session-query 0.1.5-alpha.2

package/lib/types/cold-read.d.ts

@@ -0,0 +1,27 @@
+/** One-shot cold session read through the handle-based persistence seam. */
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset, SessionSeedEventState } from '@x1a0f3n9/dsh-session';
+import type SessionPersistence from '@x1a0f3n9/dsh-session-persistence';
+/** A stored session log balanced for read-only viewing. */
+export interface ColdSessionLog {
+    /** Aliasing state of the persisted events; synthetic closers are locally owned. */
+    readonly eventState: SessionSeedEventState;
+    /** The stored header, fixed when the read handle opened. */
+    readonly header: SessionHeader;
+    /** Exact fork-inherited event count paired with {@link header}. */
+    readonly inheritedEventCount: SessionLogOffset;
+    /** Stored events plus deterministic in-memory closers for an interrupted final turn; nothing is written back. */
+    readonly events: SessionEvent[];
+}
+/**
+ * Read one complete stored session log without taking ownership or mutating
+ * storage: open a read handle, read the validated contiguous log, close the
+ * handle, and append `interruptedTurnClosers` so a log whose writer crashed
+ * mid-turn folds as a balanced transcript. Backend failures propagate
+ * unmapped — each caller owns its error taxonomy.
+ * @param persistence - the mounted persistence service.
+ * @param sessionId - the stored session to read.
+ * @param signal - optional cancellation for the open and read work.
+ * @returns an adoptable seed in a caller-owned outer array, ready for in-place Session restoration.
+ */
+export declare function readColdSessionLog(persistence: SessionPersistence, sessionId: SessionId, signal?: AbortSignal): Promise<ColdSessionLog>;
+//# sourceMappingURL=cold-read.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,29 @@
+/** Public configuration and typed failures for the combined session-query service. */
+import { HarnessError } from '@x1a0f3n9/dsh-llm';
+/** Default maximum `before`/`after` raw-event window. */
+export declare const SESSION_QUERY_READ_WINDOW_MAX = 50;
+/** Default maximum number of concurrent persisted-log reads in one batch read. */
+export declare const SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY = 4;
+/** Default maximum number of cold prepared-Session observations retained for reuse. */
+export declare const SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5;
+/** 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 reads in one batch read. Defaults to 4. */
+    persistedReadConcurrency?: number;
+    /**
+     * Maximum cold prepared-Session observations retained for reuse, keyed by
+     * durable revision. Entries pinned by active observation leases do not count
+     * against this bound until released. Defaults to 5.
+     */
+    preparedSessionCacheSize?: 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,66 @@
+/** Live/persisted logical-corpus resolution for session-query. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@x1a0f3n9/dsh-session';
+import type { SessionRecord } from './types.ts';
+/** Detached source selected for one exact read. */
+export interface LogicalSession {
+    /** Cloned source header. */
+    header: SessionHeader;
+    /** Exact fork-inherited event count paired with {@link header}. */
+    inheritedEventCount: SessionLogOffset;
+    /** 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 _persistedReadConcurrency;
+    private _persistence;
+    private readonly _optionalPersistenceFiber;
+    constructor(_ctx: Context, _persistedReadConcurrency: 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 '@x1a0f3n9/dsh-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 '@x1a0f3n9/dsh-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 '@x1a0f3n9/dsh-session';
+/**
+ * Extract searchable semantic text from one first-party session event.
+ *
+ * Structural boundaries, embedded raw streams, 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,155 @@
+/**
+ * Service Definition for combined session-history reads, traces, filters, and full-text search.
+ *
+ * @module @x1a0f3n9/dsh-session-query
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { type SessionId } from '@x1a0f3n9/dsh-session';
+import type { SessionTitleSnapshot } from '@x1a0f3n9/dsh-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';
+import { type SessionObservation, type SessionObservationOptions } from './observation.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_DEFAULT_PREPARED_SESSION_CACHE_SIZE, SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError, } from './config.ts';
+export { readColdSessionLog } from './cold-read.ts';
+export type { ColdSessionLog } from './cold-read.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';
+export type { SessionObservation, SessionObservationOptions } from './observation.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;
+    private readonly _observations;
+    constructor(ctx: Context, config?: Config);
+    /**
+     * Observe one exact live or prepared Session without a persistence listing preflight.
+     * @param sessionId - logical Session identity.
+     * @param options - cancellation and projection selection for this read.
+     * @returns a caller-owned observation lease.
+     */
+    observeSession(sessionId: SessionId, options?: SessionObservationOptions): Promise<SessionObservation>;
+    /**
+     * 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/observation.d.ts

@@ -0,0 +1,85 @@
+/** Shared live/prepared observations for Session page and lifecycle consumers. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset as SessionLogOffsetType, SessionSeqCursor } from '@x1a0f3n9/dsh-session';
+import type { SessionPersistenceRevision } from '@x1a0f3n9/dsh-session-persistence';
+import type { ProjectionSnapshot } from '@x1a0f3n9/dsh-session-projection';
+/** One exact immutable Session cut retained for the caller's read lifetime. */
+export interface SessionObservation extends Disposable {
+    /** Whether the cut came from an attached Session or a retained preparation. */
+    readonly source: 'live' | 'prepared';
+    /** Immutable Session identity metadata. */
+    readonly header: SessionHeader;
+    /** Exact fork-inherited event count paired with {@link header}. */
+    readonly inheritedEventCount: SessionLogOffsetType;
+    /**
+     * Immutable contiguous events at {@link cursor}. A live observation
+     * materializes this array on first read, so a consumer that reads only the
+     * header, cursor, or projections never copies the log.
+     */
+    readonly events: readonly SessionEvent[];
+    /** Last observed event seq, or -1 for an empty log. */
+    readonly cursor: SessionSeqCursor;
+    /** Durable source revision for a cold prepared observation. */
+    readonly revision?: SessionPersistenceRevision;
+    /** Exact projection baseline at {@link cursor}, when the registry is mounted. */
+    readonly projections?: ProjectionSnapshot;
+    /**
+     * Retain the same immutable cut for another Host owner.
+     * @returns an independently disposable lease over this observation.
+     */
+    retain(): SessionObservation;
+}
+/** Projection work and cancellation requested for one exact observation. */
+export interface SessionObservationOptions {
+    /** Optional cancellation while resolving a cold source. */
+    readonly signal?: AbortSignal;
+    /** Whether to compute every projection or leave projection state untouched. */
+    readonly projectionMode?: 'all' | 'none';
+}
+/**
+ * Builds point observations without a corpus listing preflight.
+ *
+ * Cold reads are cached per session id, keyed by the persistence instance and
+ * the `stat` revision observed before the log read: an unchanged revision
+ * reuses the restored Session without re-reading the log. The cache is bounded
+ * (least-recently-used unpinned entries are evicted past the capacity), and
+ * entries pinned by active leases survive eviction and replacement — a lease's
+ * cut stays valid for the lease lifetime even after a newer revision lands.
+ */
+export declare class SessionObservationReader {
+    private readonly ctx;
+    private readonly cacheCapacity;
+    private readonly cache;
+    /**
+     * @param ctx - context carrying Session and optional persistence/projection services.
+     * @param cacheCapacity - maximum unpinned cold observations retained for reuse.
+     */
+    constructor(ctx: Context, cacheCapacity?: number);
+    /**
+     * Observe one live-preferred Session and retain a cold preparation until disposal.
+     * @param sessionId - logical Session identity.
+     * @param options - cancellation and all-or-none projection computation for this read.
+     * @returns one exact immutable observation.
+     */
+    read(sessionId: SessionId, options?: SessionObservationOptions): Promise<SessionObservation>;
+    /** Observe the stored snapshot, mapping absence and backend failures to the query taxonomy. */
+    private statSource;
+    /** Read the complete balanced cold log, mapping backend failures to the query taxonomy. */
+    private loadSource;
+    /** Return a still-valid cached entry and mark it most recently used. */
+    private cachedEntry;
+    /** Insert or replace the entry for one id, then evict past the capacity. */
+    private store;
+    /**
+     * Evict oldest unpinned entries until the cache fits its capacity again.
+     * Runs on store and whenever a lease release unpins an entry, so leases
+     * that pinned every candidate cannot leave the cache over budget for good.
+     * @param keep - the entry being stored, about to be leased; never evicted.
+     */
+    private evictPastCapacity;
+    /** Build one disposable lease over a cached entry, pinning it until every lease releases. */
+    private preparedLease;
+    private live;
+    private preparedProjections;
+}
+//# sourceMappingURL=observation.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 '@x1a0f3n9/dsh-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, SessionSeq, SurfaceEvent } from '@x1a0f3n9/dsh-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: SessionSeq): 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