@deepseek-ai/dsh-session-query-sqlite 0.0.1-rc.1

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-query-sqlite`.
+* @module @deepseek-ai/dsh-session-query-sqlite/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-query-sqlite";
+/** Cordis companion plugin name. */
+const name = "session-query-sqlite-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: reconciliation, cursor generations, and derived-index
+* ownership are validated at each serialized query boundary.
+*/
+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/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Concrete session-query service with SQLite FTS5 over the live-preferred corpus.
+ *
+ * @module @deepseek-ai/dsh-session-query-sqlite
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import SessionQueryService from '@deepseek-ai/dsh-session-query';
+import type { Config as SessionQueryConfig, SessionEventSearchPage, SessionEventSearchRequest, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest } from '@deepseek-ai/dsh-session-query';
+import { type JournalMode } from './schema.ts';
+export { SESSION_QUERY_SQLITE_APPLICATION_ID, SESSION_QUERY_SQLITE_SCHEMA_VERSION, type JournalMode, } from './schema.ts';
+/** Boot-context slot for a launcher-owned absolute path to this process's derived query index. */
+export declare const SESSION_QUERY_SQLITE_PATH_KEY = "launcherSessionQueryPath";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Launcher-owned absolute path to this process's disposable derived query index. */
+        launcherSessionQueryPath?: string;
+    }
+}
+/** Default result page size. */
+export declare const SESSION_QUERY_SQLITE_DEFAULT_LIMIT = 20;
+/** Maximum accepted result page size. */
+export declare const SESSION_QUERY_SQLITE_MAX_LIMIT = 100;
+/** Default maximum snippet length in Unicode code points. */
+export declare const SESSION_QUERY_SQLITE_SNIPPET_CHARS = 240;
+/** SQLite module/handle opening phase. */
+export type OpenAt = 'startup' | 'first-search';
+/** Combined session-query configuration backed by SQLite full-text search. */
+export interface Config extends SessionQueryConfig {
+    /**
+     * Dedicated derived-index path; `:memory:` is supported for ephemeral
+     * indexes. Missing directories and database files are created owner-only on
+     * POSIX filesystems; existing modes are preserved.
+     */
+    path: string;
+    /** Open the SQLite module and handle at service activation or the first search. Defaults to `startup`. */
+    openAt?: OpenAt;
+    /** SQLite journal mode. Defaults to `wal`. */
+    journalMode?: JournalMode;
+    /** Page size when a request omits `limit`. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 20. */
+    defaultLimit?: number;
+    /** Largest accepted page size. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 100. */
+    maxLimit?: number;
+    /** Maximum snippet length in Unicode code points. Defaults to 240. */
+    snippetChars?: number;
+    /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
+    persistedInspectConcurrency?: number;
+}
+interface ResolvedConfig {
+    path: string;
+    openAt: OpenAt;
+    journalMode: JournalMode;
+    defaultLimit: number;
+    maxLimit: number;
+    snippetChars: number;
+    readWindowMax: number;
+    persistedInspectConcurrency: number;
+}
+/** Concrete SQLite owner of the combined `ctx.sessionQuery` service. */
+export declare class SessionQuerySqlite extends SessionQueryService {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Validated and defaulted backend configuration. */
+    readonly config: ResolvedConfig;
+    private readonly _instance;
+    private _ready;
+    private _db;
+    private _persistenceBinding;
+    private _lastPersistenceIdentity;
+    private _persistenceEpoch;
+    private _globalGeneration;
+    private _localGeneration;
+    private _tail;
+    private _closed;
+    private _closePromise;
+    private readonly _optionalPersistenceFiber;
+    constructor(ctx: Context, config: Config);
+    /** Open eagerly only when activation owns the configured readiness boundary. */
+    protected [Service.init](): Promise<void>;
+    searchSessions(request: SessionSearchRequest, exec?: SessionSearchExecContext): Promise<SessionSearchPage<SessionSearchHit>>;
+    searchEvents(request: SessionEventSearchRequest, exec?: SessionSearchExecContext): Promise<SessionEventSearchPage>;
+    /** Close the database after every accepted operation reaches quiescence. */
+    close(): Promise<void>;
+    private _close;
+    private _open;
+    private _ensureReady;
+    private _serialized;
+    private _reconcile;
+    private _observeStable;
+    private _mainGeneration;
+    private _deleteSession;
+    private _replacePersistedSession;
+    private _replaceLiveSession;
+    private _querySessions;
+    private _queryEvents;
+    private _targetObservation;
+    private _sessionHit;
+    private _eventHit;
+    private _requireDb;
+    private _isClosed;
+}
+export default SessionQuerySqlite;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-query-sqlite`.
+ * @module @deepseek-ai/dsh-session-query-sqlite/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-query-sqlite-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/query.d.ts

@@ -0,0 +1,106 @@
+/** Request normalization, parameterized predicates, and result presentation. */
+import type { SessionEventMetadataFilter, SessionEventSearchRequest, SessionResultFilter, SessionSearchCursor, SessionSearchRequest } from '@deepseek-ai/dsh-session-query';
+/** Collision-free marker inserted before an FTS5 match by `highlight()`. */
+export declare const FTS_HIGHLIGHT_START = "\uFDD0";
+/** Collision-free marker inserted after an FTS5 match by `highlight()`. */
+export declare const FTS_HIGHLIGHT_END = "\uFDD1";
+/** Largest page size whose internal lookahead remains an exact SQLite integer binding. */
+export declare const SQLITE_MAX_PAGE_LIMIT: number;
+/** Portable host-parameter ceiling shared by predicate and statement builders. */
+export declare const SQLITE_PORTABLE_VARIABLE_LIMIT = 32766;
+/** Supported outer-predicate budget that keeps SQLite FTS5 MATCH usable. */
+export declare const SQLITE_FTS5_OUTER_PREDICATE_LIMIT = 14;
+/**
+ * Reject prospective SQLite binding growth beyond the portable ceiling.
+ * @param count - binding count at the current construction boundary.
+ */
+export declare function assertPortableBindingCount(count: number): void;
+/**
+ * Reject compiled outer predicates beyond the supported FTS5 planner budget.
+ * @param count - predicate count including fixed statement predicates.
+ */
+export declare function assertFts5OuterPredicateCount(count: number): void;
+/** Limit defaults needed to normalize a search request. */
+export interface QueryLimits {
+    /** Page size used when the request omits one. */
+    defaultLimit: number;
+    /** Largest accepted page size. */
+    maxLimit: number;
+}
+/** Normalized cross-session request. */
+export interface NormalizedSessionRequest {
+    query: string;
+    sessionFilters: readonly SessionResultFilter[];
+    eventFilters: readonly SessionEventMetadataFilter[];
+    limit: number;
+    cursor?: SessionSearchCursor;
+}
+/** Normalized within-session request. */
+export interface NormalizedEventRequest {
+    sessionId: SessionEventSearchRequest['sessionId'];
+    query: string;
+    filters: readonly SessionEventMetadataFilter[];
+    limit: number;
+    cursor?: SessionSearchCursor;
+}
+/** Parameterized SQL predicate fragment. */
+export interface SqlWhere {
+    /** SQL without the leading `WHERE`. */
+    sql: string;
+    /** Bindings in placeholder order. */
+    params: Array<string | number>;
+    /** Number of compiled predicates in `sql`. */
+    predicateCount: number;
+}
+/**
+ * Validate and canonicalize a cross-session request.
+ * @param request - caller-provided query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with explicit arrays and limit.
+ */
+export declare function normalizeSessionRequest(request: SessionSearchRequest, limits: QueryLimits): NormalizedSessionRequest;
+/**
+ * Validate and canonicalize a within-session request.
+ * @param request - caller-provided target, query, filters, limit, and cursor.
+ * @param limits - configured default and maximum page sizes.
+ * @returns normalized request with an explicit filter array and limit.
+ */
+export declare function normalizeEventRequest(request: SessionEventSearchRequest, limits: QueryLimits): NormalizedEventRequest;
+/**
+ * Compile logical-session predicates against selected-document columns.
+ * @param filters - validated ANDed logical-session clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export declare function buildSessionWhere(filters: readonly SessionResultFilter[]): SqlWhere;
+/**
+ * Compile event metadata predicates against selected-document columns.
+ * @param filters - validated ANDed event metadata clauses.
+ * @returns parameterized SQL fragment and ordered bindings.
+ */
+export declare function buildEventWhere(filters: readonly SessionEventMetadataFilter[]): SqlWhere;
+/**
+ * Quote caller text as one FTS5 phrase so query syntax remains inert data.
+ * @param query - normalized caller query.
+ * @returns FTS5 expression containing one escaped literal phrase.
+ */
+export declare function quoteFtsData(query: string): string;
+/**
+ * Remove reserved marker collisions before text enters FTS5 or MATCH.
+ * @param text - extracted document text or normalized caller query.
+ * @returns text with reserved noncharacters mapped to replacement characters.
+ */
+export declare function sanitizeFtsText(text: string): string;
+/**
+ * Build the stable normalized request identity stored in opaque cursors.
+ * @param request - normalized request whose filter ordering is canonicalized.
+ * @returns deterministic JSON identity for cursor binding.
+ */
+export declare function requestFingerprint(request: NormalizedSessionRequest | NormalizedEventRequest): string;
+/**
+ * Build a whitespace-normalized excerpt no longer than `maxChars`.
+ * @param markedText - complete document with FTS5 `highlight()` markers.
+ * @param maxChars - maximum result length in Unicode code points.
+ * @returns bounded plain-text snippet.
+ */
+export declare function makeSnippet(markedText: string, maxChars: number): string;
+//# sourceMappingURL=query.d.ts.map

package/lib/types/schema.d.ts

@@ -0,0 +1,16 @@
+/** SQLite schema for the disposable session full-text read model. */
+import type { DatabaseSync } from 'node:sqlite';
+/** Current derived-index schema version. Incompatible versions reset in place. */
+export declare const SESSION_QUERY_SQLITE_SCHEMA_VERSION = 8;
+/** SQLite application id protecting unrelated databases from derived resets. */
+export declare const SESSION_QUERY_SQLITE_APPLICATION_ID = 1146308689;
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist';
+/**
+ * Open, validate, and initialize persistent and connection-local schemas.
+ * @param path - dedicated derived-index path or `:memory:`; missing filesystem paths are created owner-only.
+ * @param journalMode - validated SQLite journal mode.
+ * @returns initialized database handle owned by the search service.
+ */
+export declare function openSearchDatabase(path: string, journalMode: JournalMode): Promise<DatabaseSync>;
+//# sourceMappingURL=schema.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@deepseek-ai/dsh-session-query-sqlite",
+  "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session-query/session-query-sqlite"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}