dsh-plugin-sessiongraph-sqlite 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CC ZHAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/database.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Connection ownership for the local-conversation index: where an index root's database lives, the
+ * schema-version gate every connection passes before serving a query, and the bounded pool that
+ * keeps recently queried roots open.
+ *
+ * The indexer writes `<indexRoot>/index.db` under a temp name and renames it into place, so a reader
+ * always sees a complete file. This store still opens READ-ONLY and never repairs, migrates, or
+ * writes anything: an index it cannot read is reported as corrupt rather than silently treated as
+ * empty, because "no match" and "cannot answer" must never look the same to the model.
+ * @module dsh-plugin-sessiongraph-sqlite/database
+ */
+import { DatabaseSync } from 'node:sqlite';
+/**
+ * The absolute path of an index root's database.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns the database path, whether or not it exists.
+ */
+export declare function databasePath(indexRoot: string): string;
+/**
+ * Whether an index root holds an index at all.
+ *
+ * A synchronous `stat` is deliberate: the seam asks every registered store this question on every
+ * query, so the probe must not open a database, parse a header, or touch SQLite. Existence is the
+ * claim; whether the file is readable is decided later, by {@link openIndex}, which fails loud.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns true when `<indexRoot>/index.db` exists as a regular file.
+ */
+export declare function indexExists(indexRoot: string): boolean;
+/**
+ * Open one index root's database read-only and verify its schema version.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns the open, version-checked connection; the caller owns closing it.
+ * @throws SessiongraphError with code `SESSIONGRAPH_CORRUPT` when the file cannot be opened, is not
+ * SQLite, or was written at another schema version. Never returns an empty database as a stand-in:
+ * a silent empty result would be indistinguishable from "no such conversation".
+ */
+export declare function openIndex(indexRoot: string): DatabaseSync;
+/**
+ * A bounded set of open index connections keyed by index root, evicting the least recently used one
+ * when full. Every connection the pool hands out stays valid until {@link close}: eviction and
+ * disposal both close connections, so a caller holds a connection only for the duration of one
+ * synchronous query.
+ *
+ * A connection is opened against one specific on-disk file. The indexer replaces that file wholesale
+ * (rename over the old path), and POSIX unlink semantics mean an already-open read-only connection
+ * keeps serving the REPLACED file's bytes indefinitely — reopening is the only way to see the new
+ * index. `acquire` detects that swap by comparing the device/inode recorded at open time against the
+ * path's current identity, so a cache hit never silently serves an index an indexing run has already
+ * superseded.
+ */
+export declare class IndexPool {
+    private readonly capacity;
+    private readonly open;
+    private disposed;
+    /**
+     * @param capacity - largest number of simultaneously open indexes; at least 1.
+     */
+    constructor(capacity: number);
+    /**
+     * The connection for an index root, opening and caching it on first use. Reopens automatically
+     * when the file on disk is no longer the one the cached connection was opened against.
+     * @param indexRoot - directory the seam routed a request to.
+     * @returns the open, version-checked connection, current as of this call.
+     */
+    acquire(indexRoot: string): DatabaseSync;
+    /** Close every open connection; further {@link acquire} calls fail as `SESSIONGRAPH_UNAVAILABLE`. */
+    close(): void;
+    /** Close least-recently-used connections until the pool fits its capacity. */
+    private evictOverflow;
+}
+//# sourceMappingURL=database.d.ts.map

package/lib/database.js

@@ -0,0 +1,210 @@
+/**
+ * Connection ownership for the local-conversation index: where an index root's database lives, the
+ * schema-version gate every connection passes before serving a query, and the bounded pool that
+ * keeps recently queried roots open.
+ *
+ * The indexer writes `<indexRoot>/index.db` under a temp name and renames it into place, so a reader
+ * always sees a complete file. This store still opens READ-ONLY and never repairs, migrates, or
+ * writes anything: an index it cannot read is reported as corrupt rather than silently treated as
+ * empty, because "no match" and "cannot answer" must never look the same to the model.
+ * @module dsh-plugin-sessiongraph-sqlite/database
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { INDEX_RELATIVE_PATH, META_SCHEMA_VERSION, SCHEMA_VERSION, SessiongraphError, } from 'dsh-plugin-sessiongraph-service';
+/**
+ * The absolute path of an index root's database.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns the database path, whether or not it exists.
+ */
+export function databasePath(indexRoot) {
+    return join(indexRoot, INDEX_RELATIVE_PATH);
+}
+/**
+ * Whether an index root holds an index at all.
+ *
+ * A synchronous `stat` is deliberate: the seam asks every registered store this question on every
+ * query, so the probe must not open a database, parse a header, or touch SQLite. Existence is the
+ * claim; whether the file is readable is decided later, by {@link openIndex}, which fails loud.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns true when `<indexRoot>/index.db` exists as a regular file.
+ */
+export function indexExists(indexRoot) {
+    try {
+        return statSync(databasePath(indexRoot)).isFile();
+    }
+    catch {
+        // Only the existence probe runs in the try. A missing file, a missing directory, or no
+        // permission to look all mean the same thing to the seam: this store cannot serve the root.
+        return false;
+    }
+}
+/**
+ * Read the schema version stamped into an open index.
+ * @param db - an open connection.
+ * @returns the recorded version.
+ * @throws SessiongraphError with code `SESSIONGRAPH_CORRUPT` when the row is missing or not an
+ * integer, because such a file cannot be read through this code's assumptions.
+ */
+function readSchemaVersion(db) {
+    let row;
+    try {
+        row = db.prepare('SELECT value FROM meta WHERE key = ?').get(META_SCHEMA_VERSION);
+    }
+    catch (cause) {
+        // A file that is not SQLite at all throws here rather than in the constructor (SQLite opens
+        // lazily and only validates the header on first read). That is still a corrupt index, not an
+        // unavailable one: `indexes()` already told the seam the file is there.
+        throw new SessiongraphError(`the session-graph index is not a readable SQLite database (${describe(cause)})`, 'SESSIONGRAPH_CORRUPT');
+    }
+    const raw = row?.['value'];
+    const version = typeof raw === 'string' ? Number(raw) : typeof raw === 'number' ? raw : Number.NaN;
+    if (!Number.isInteger(version)) {
+        throw new SessiongraphError('the session-graph index records no readable schema version', 'SESSIONGRAPH_CORRUPT');
+    }
+    return version;
+}
+/**
+ * Open one index root's database read-only and verify its schema version.
+ * @param indexRoot - directory the seam routed a request to.
+ * @returns the open, version-checked connection; the caller owns closing it.
+ * @throws SessiongraphError with code `SESSIONGRAPH_CORRUPT` when the file cannot be opened, is not
+ * SQLite, or was written at another schema version. Never returns an empty database as a stand-in:
+ * a silent empty result would be indistinguishable from "no such conversation".
+ */
+export function openIndex(indexRoot) {
+    const path = databasePath(indexRoot);
+    let db;
+    try {
+        db = new DatabaseSync(path, { readOnly: true });
+    }
+    catch (cause) {
+        throw new SessiongraphError(`cannot open the session-graph index at "${path}" (${describe(cause)})`, 'SESSIONGRAPH_CORRUPT');
+    }
+    let version;
+    try {
+        version = readSchemaVersion(db);
+    }
+    catch (error) {
+        closeQuietly(db);
+        throw error;
+    }
+    if (version !== SCHEMA_VERSION) {
+        closeQuietly(db);
+        throw new SessiongraphError(`the session-graph index at "${path}" is schema version ${version}; this store reads version ${SCHEMA_VERSION}`, 'SESSIONGRAPH_CORRUPT');
+    }
+    return db;
+}
+/** Close without letting a secondary failure mask the error already being reported. */
+function closeQuietly(db) {
+    try {
+        db.close();
+    }
+    catch {
+        // The connection is being abandoned because it is unusable; a close failure changes nothing.
+    }
+}
+/** One diagnostic line from a caught value, without assuming it is an Error. */
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * A path's current on-disk identity, or `undefined` when it cannot be stat'd (most commonly: an
+ * indexing run's atomic replace is between removing the old file and renaming the new one into
+ * place). That absence is treated as "unknown, not gone" by every caller — a transient rebuild
+ * window must never look like a missing index.
+ * @param path - the file to identify.
+ */
+function identify(path) {
+    try {
+        const stats = statSync(path);
+        return { dev: stats.dev, ino: stats.ino };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether two identities name the same underlying file. */
+function sameIdentity(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * A bounded set of open index connections keyed by index root, evicting the least recently used one
+ * when full. Every connection the pool hands out stays valid until {@link close}: eviction and
+ * disposal both close connections, so a caller holds a connection only for the duration of one
+ * synchronous query.
+ *
+ * A connection is opened against one specific on-disk file. The indexer replaces that file wholesale
+ * (rename over the old path), and POSIX unlink semantics mean an already-open read-only connection
+ * keeps serving the REPLACED file's bytes indefinitely — reopening is the only way to see the new
+ * index. `acquire` detects that swap by comparing the device/inode recorded at open time against the
+ * path's current identity, so a cache hit never silently serves an index an indexing run has already
+ * superseded.
+ */
+export class IndexPool {
+    capacity;
+    open = new Map();
+    disposed = false;
+    /**
+     * @param capacity - largest number of simultaneously open indexes; at least 1.
+     */
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    /**
+     * The connection for an index root, opening and caching it on first use. Reopens automatically
+     * when the file on disk is no longer the one the cached connection was opened against.
+     * @param indexRoot - directory the seam routed a request to.
+     * @returns the open, version-checked connection, current as of this call.
+     */
+    acquire(indexRoot) {
+        if (this.disposed) {
+            throw new SessiongraphError('the session-graph store is disposed', 'SESSIONGRAPH_UNAVAILABLE');
+        }
+        const cached = this.open.get(indexRoot);
+        if (cached !== undefined) {
+            const current = identify(databasePath(indexRoot));
+            // `undefined` means the path is transiently unstatable — most likely an indexing run's replace
+            // is mid-flight between removing the old file and renaming the new one into place. Keep serving
+            // the connection we have rather than treating a rebuild-in-progress as a missing index.
+            if (current === undefined || sameIdentity(current, cached.identity)) {
+                // Re-insert to mark most recently used; Map iteration order is insertion order.
+                this.open.delete(indexRoot);
+                this.open.set(indexRoot, cached);
+                return cached.db;
+            }
+            cached.db.close();
+            this.open.delete(indexRoot);
+        }
+        const db = openIndex(indexRoot);
+        const identity = identify(databasePath(indexRoot));
+        // Only `undefined` when the file vanishes in the instant between opening it and this stat — an
+        // unprovokable race in tests. The sentinel never matches a real identity, so the next acquire()
+        // is forced to re-verify rather than trusting an unconfirmed connection indefinitely.
+        /* v8 ignore next */
+        this.open.set(indexRoot, { db, identity: identity ?? { dev: -1, ino: -1 } });
+        this.evictOverflow();
+        return db;
+    }
+    /** Close every open connection; further {@link acquire} calls fail as `SESSIONGRAPH_UNAVAILABLE`. */
+    close() {
+        this.disposed = true;
+        for (const { db } of this.open.values())
+            db.close();
+        this.open.clear();
+    }
+    /** Close least-recently-used connections until the pool fits its capacity. */
+    evictOverflow() {
+        while (this.open.size > this.capacity) {
+            // Map iteration starts at the least recently used entry, and `acquire` re-inserts on a hit,
+            // so the first entry is always the eviction candidate.
+            for (const [root, entry] of this.open) {
+                entry.db.close();
+                this.open.delete(root);
+                break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=database.js.map

package/lib/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SQLite store for `ctx.sessiongraph`. One plugin instance registers one store that answers every
+ * seam operation from the on-disk conversation index an indexer writes to
+ * `<indexRoot>/index.db`, opening each root read-only and keeping a bounded set of connections warm.
+ *
+ * The store is host-local by construction: `node:sqlite` opens a path on the machine running the
+ * harness, so availability is decided against the host filesystem rather than `ctx.fs`. Availability
+ * is a synchronous `stat` of the index file (the seam asks this on every query); the file is only
+ * opened when a query actually needs it.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
+ * unregisters from `ctx.sessiongraph` first, then closes every open connection.
+ * @module dsh-plugin-sessiongraph-sqlite
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { IndexPool, databasePath, indexExists, openIndex } from './database.ts';
+export { toEntry, toHitSubject, toSessionSummary, toWorkspaceStat } from './rows.ts';
+export type { IndexRow } from './rows.ts';
+export { search, session, status, timeline, workspaces } from './queries.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "sessiongraph-sqlite";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Branded identity this store reserves on the seam. */
+export declare const DEFAULT_STORE_ID = "sessiongraph-sqlite";
+/** Default number of index databases kept open at once. */
+export declare const DEFAULT_MAX_OPEN_DATABASES = 4;
+/** Default ceiling on one rendered search snippet, in characters. */
+export declare const DEFAULT_MAX_SNIPPET_CHARS = 240;
+/**
+ * Default index root, the one `dsh-plugin-sessiongraph-sessions` builds into. Used only when a
+ * request's `indexRoot` is empty — an explicit root always wins, so a deployment that moved the
+ * index is served from where it actually is.
+ */
+export declare const DEFAULT_INDEX_ROOT: string;
+/** Plugin configuration: the bounds the seam's requests cannot express. */
+export interface Config {
+    /**
+     * Largest number of index databases held open at once (default 4). The least recently queried
+     * connection closes when the limit is exceeded; a root queried again simply reopens.
+     */
+    maxOpenDatabases?: number;
+    /**
+     * Largest excerpt rendered per search hit (default 240), in characters. Brackets marking matched
+     * terms are added after this bound, so they never shorten the visible text.
+     */
+    maxSnippetChars?: number;
+    /**
+     * Index root used when a request leaves `indexRoot` empty (default `~/.dsh/sessiongraph`). Kept
+     * configurable so a profile can move the index without rebuilding the plugin.
+     */
+    defaultIndexRoot?: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the SQLite session-graph store.
+ * @param ctx - the plugin context (must inject `sessiongraph`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,126 @@
+/**
+ * SQLite store for `ctx.sessiongraph`. One plugin instance registers one store that answers every
+ * seam operation from the on-disk conversation index an indexer writes to
+ * `<indexRoot>/index.db`, opening each root read-only and keeping a bounded set of connections warm.
+ *
+ * The store is host-local by construction: `node:sqlite` opens a path on the machine running the
+ * harness, so availability is decided against the host filesystem rather than `ctx.fs`. Availability
+ * is a synchronous `stat` of the index file (the seam asks this on every query); the file is only
+ * opened when a query actually needs it.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
+ * unregisters from `ctx.sessiongraph` first, then closes every open connection.
+ * @module dsh-plugin-sessiongraph-sqlite
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { SessiongraphStoreId, assertNever } from 'dsh-plugin-sessiongraph-service';
+import { IndexPool, indexExists } from "./database.js";
+import { search, session, status, timeline, workspaces } from "./queries.js";
+export { IndexPool, databasePath, indexExists, openIndex } from "./database.js";
+export { toEntry, toHitSubject, toSessionSummary, toWorkspaceStat } from "./rows.js";
+export { search, session, status, timeline, workspaces } from "./queries.js";
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'sessiongraph-sqlite';
+/** Services required by this plugin. */
+export const inject = ['sessiongraph'];
+/** Branded identity this store reserves on the seam. */
+export const DEFAULT_STORE_ID = 'sessiongraph-sqlite';
+/** Default number of index databases kept open at once. */
+export const DEFAULT_MAX_OPEN_DATABASES = 4;
+/** Default ceiling on one rendered search snippet, in characters. */
+export const DEFAULT_MAX_SNIPPET_CHARS = 240;
+/**
+ * Default index root, the one `dsh-plugin-sessiongraph-sessions` builds into. Used only when a
+ * request's `indexRoot` is empty — an explicit root always wins, so a deployment that moved the
+ * index is served from where it actually is.
+ */
+export const DEFAULT_INDEX_ROOT = join(homedir(), '.dsh', 'sessiongraph');
+export const Config = z.object({
+    maxOpenDatabases: z.number().default(DEFAULT_MAX_OPEN_DATABASES),
+    maxSnippetChars: z.number().default(DEFAULT_MAX_SNIPPET_CHARS),
+    defaultIndexRoot: z.string().default(DEFAULT_INDEX_ROOT),
+});
+/**
+ * Register the SQLite session-graph store.
+ * @param ctx - the plugin context (must inject `sessiongraph`).
+ * @param config - the resolved plugin configuration.
+ */
+export function apply(ctx, config) {
+    const resolved = config;
+    assertPositiveInteger('maxOpenDatabases', resolved.maxOpenDatabases);
+    assertPositiveInteger('maxSnippetChars', resolved.maxSnippetChars);
+    if (resolved.defaultIndexRoot.trim() === '') {
+        throw new Error('sessiongraph-sqlite: defaultIndexRoot must be a non-empty path');
+    }
+    const pool = new IndexPool(resolved.maxOpenDatabases);
+    // `ctx.sessiongraph` is reached through `ctx.get` because the seam package does not (yet) augment
+    // `Context` with it; `inject` guarantees the service is present before `apply` runs.
+    const seam = ctx.get('sessiongraph');
+    const store = {
+        id: SessiongraphStoreId(DEFAULT_STORE_ID),
+        async indexes(indexRoot, signal) {
+            signal?.throwIfAborted();
+            return indexExists(resolveIndexRoot(resolved, indexRoot));
+        },
+        query(request, signal) {
+            signal?.throwIfAborted();
+            return Promise.resolve(run(pool, resolved, request));
+        },
+    };
+    ctx.effect(function* () {
+        // Registered first, so it disposes LAST: the store unregisters before its connections close,
+        // and no query can be routed to a pool that is already shut.
+        yield () => {
+            pool.close();
+        };
+        yield seam.registerStore(store);
+    }, 'sessiongraph-sqlite');
+}
+/**
+ * The root a request targets: its own `indexRoot`, or the configured default when it left that empty.
+ * @param config - the resolved plugin configuration.
+ * @param indexRoot - the request's root.
+ * @returns the root to stat and open.
+ */
+function resolveIndexRoot(config, indexRoot) {
+    return indexRoot.trim() === '' ? config.defaultIndexRoot : indexRoot;
+}
+/**
+ * Answer one request from the pooled connection for its index root.
+ * @param pool - the store's connection pool.
+ * @param config - the resolved plugin configuration.
+ * @param request - the normalized seam request.
+ * @returns the result member matching `request.operation`.
+ */
+function run(pool, config, request) {
+    const indexRoot = resolveIndexRoot(config, request.indexRoot);
+    // `status` is the one operation that answers without an index, so it must not acquire a
+    // connection up front. `ctx.sessiongraph` routes only to a store that claimed the root, but a
+    // direct caller (a test, a future consumer) may still ask `status` about a root that has none.
+    if (request.operation === 'status') {
+        return status(pool, indexRoot);
+    }
+    const db = pool.acquire(indexRoot);
+    switch (request.operation) {
+        case 'search':
+            return search(db, request, config.maxSnippetChars);
+        case 'session':
+            return session(db, request);
+        case 'timeline':
+            return timeline(db, request);
+        case 'workspaces':
+            return workspaces(db, request);
+        /* v8 ignore next -- exhaustive over the seam's closed operation union; unreachable. */
+        default:
+            return assertNever(request);
+    }
+}
+/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(field, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`sessiongraph-sqlite: ${field} must be a positive integer`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/invariant.d.ts

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

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-sessiongraph-sqlite`.
+ * @module dsh-plugin-sessiongraph-sqlite/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-sessiongraph-sqlite';
+/** Cordis companion plugin name. */
+export const name = 'sessiongraph-sqlite-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the store owns no mutable harness data and emits no event. Its connection
+ * pool is private, and the index it reads is a file another plugin writes, so there is no owned
+ * relation between two harness-visible values to compare.
+ */
+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.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/queries.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The five seam operations against one open index database. Every function here is synchronous:
+ * `node:sqlite` is a synchronous binding, so a query either completes within one turn or throws, and
+ * the store's async surface exists for the seam's contract rather than for I/O interleaving.
+ *
+ * User-supplied strings never reach a statement as SQL text. Every filter is a `?` binding; the only
+ * text shaped from input is a `LIKE` pattern, and its wildcard characters are escaped so a workspace
+ * path containing `%` or `_` still matches literally.
+ * @module dsh-plugin-sessiongraph-sqlite/queries
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { SessiongraphSearchRequest, SessiongraphSearchResult, SessiongraphSessionRequest, SessiongraphSessionResult, SessiongraphStatusResult, SessiongraphTimelineRequest, SessiongraphTimelineResult, SessiongraphWorkspacesRequest, SessiongraphWorkspacesResult } from 'dsh-plugin-sessiongraph-service';
+import type { IndexPool } from './database.ts';
+/**
+ * Full-text search across indexed history.
+ *
+ * Ordering is `bm25`, then newest, then entry id. `bm25` is chosen over plain recency because a
+ * search result list is read top-down and the caller wants the best match first, not merely the most
+ * recent one. Ranking alone is NOT a total order: equally scored rows (extremely common for short
+ * entries and bigram queries) come back in whatever order the scan produced, which would make
+ * `LIMIT`/`OFFSET` paging skip and duplicate rows between pages. Appending `e.time DESC, e.id ASC`
+ * supplies a deterministic total order without displacing relevance, since `entry.id` is unique and
+ * UNIQUE breaks every remaining tie. That is also why this is the one operation whose page order is
+ * stable across requests against an unchanged index.
+ * @param db - the open index connection.
+ * @param request - the search query.
+ * @param maxSnippetChars - largest excerpt the plugin will render per hit.
+ * @returns the page of hits, the pre-pagination total, and whether anything was cut.
+ */
+export declare function search(db: DatabaseSync, request: SessiongraphSearchRequest, maxSnippetChars: number): SessiongraphSearchResult;
+/**
+ * Read one session's metadata, a page of its entries in the session's own chronological order, and
+ * the sessions delegated from it.
+ * @param db - the open index connection.
+ * @param request - the session query.
+ * @returns the session summary, entry page, children, and whether more entries exist.
+ */
+export declare function session(db: DatabaseSync, request: SessiongraphSessionRequest): SessiongraphSessionResult;
+/**
+ * List sessions newest-first by last activity.
+ * @param db - the open index connection.
+ * @param request - the timeline query.
+ * @returns the page of session summaries and whether more exist.
+ */
+export declare function timeline(db: DatabaseSync, request: SessiongraphTimelineRequest): SessiongraphTimelineResult;
+/**
+ * Enumerate indexed workspaces, most recently active first.
+ * @param db - the open index connection.
+ * @param request - the workspaces query.
+ * @returns the page of workspace statistics and the pre-limit total.
+ */
+export declare function workspaces(db: DatabaseSync, request: SessiongraphWorkspacesRequest): SessiongraphWorkspacesResult;
+/**
+ * Report the index's own state.
+ *
+ * This is the one operation that answers when no index exists: a caller that never indexed anything
+ * needs to learn that fact, and every other operation fails loud instead of pretending the store is
+ * empty. A file that exists but cannot be read is still `SESSIONGRAPH_CORRUPT` — `indexes()` already
+ * claimed the root, so quietly downgrading it to "not indexed" would hide a damaged index.
+ * @param pool - the store's connection pool.
+ * @param indexRoot - directory the seam routed the request to.
+ * @returns the index summary, or the zero result for a root that holds no index.
+ */
+export declare function status(pool: IndexPool, indexRoot: string): SessiongraphStatusResult;
+//# sourceMappingURL=queries.d.ts.map

package/lib/queries.js

@@ -0,0 +1,430 @@
+/**
+ * The five seam operations against one open index database. Every function here is synchronous:
+ * `node:sqlite` is a synchronous binding, so a query either completes within one turn or throws, and
+ * the store's async surface exists for the seam's contract rather than for I/O interleaving.
+ *
+ * User-supplied strings never reach a statement as SQL text. Every filter is a `?` binding; the only
+ * text shaped from input is a `LIKE` pattern, and its wildcard characters are escaped so a workspace
+ * path containing `%` or `_` still matches literally.
+ * @module dsh-plugin-sessiongraph-sqlite/queries
+ */
+import { statSync } from 'node:fs';
+import { META_INDEXED_AT, SessiongraphError, SessiongraphSessionId, highlightTerms, matchExpression, } from 'dsh-plugin-sessiongraph-service';
+import { databasePath } from "./database.js";
+import { toEntry, toHitSubject, toSessionSummary, toWorkspaceStat } from "./rows.js";
+/** Every `session` column the summary projection reads. */
+const SESSION_COLUMNS = [
+    'id',
+    'workspace',
+    'title',
+    'created_at',
+    'last_at',
+    'parent_session',
+    'origin',
+    'agent_preset',
+    'turns',
+    'entries',
+].join(', ');
+/** The one `entry` row shape every query below selects, so the projection never drifts by query. */
+const ENTRY_COLUMNS = 'seq, time, kind, turn, text, clipped';
+/**
+ * `source_path` prefix the indexer writes for a conversation that is still running, before its log
+ * exists on disk. Spelled out here instead of imported from the indexer package: a store depends only
+ * on the seam, and this is a value shared through the on-disk format, not through code. A session
+ * ends and is re-indexed from a real path, at which point its row no longer matches.
+ */
+const LIVE_SOURCE_LIKE = 'live://%';
+/** Run a statement and return its rows already typed as raw records. */
+function rows(db, sql, params = []) {
+    return db.prepare(sql).all(...params);
+}
+/** Read a `count(*) AS total` aggregate; an empty table yields 0, not undefined. */
+function count(db, sql, params = []) {
+    const row = db.prepare(sql).get(...params);
+    const value = row?.['total'];
+    return typeof value === 'number' ? value : 0;
+}
+/**
+ * Coerce a request bound into a non-negative integer. A caller-supplied `limit`/`offset` is not
+ * trusted to be well formed — `LIMIT -1` would mean "no limit" in SQLite, which is exactly the
+ * unbounded answer the seam's `limit` exists to prevent.
+ * @param value - the requested bound.
+ * @returns the bound as a non-negative integer.
+ */
+function bound(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.floor(value));
+}
+/** Escape the wildcard characters in a string that becomes a `LIKE` pattern. */
+function escapeLike(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+}
+/**
+ * Build the workspace predicate for one side of a query.
+ *
+ * A path that ends with `/` is a PREFIX filter ("everything under this directory"); any other value
+ * is an exact `cwd` match. That distinction is the wrong way round from most APIs, and it is
+ * deliberate: a caller filtering on an exact workspace usually has the exact path already, while a
+ * prefix filter is the one that needs a marker to say "this is not a full path".
+ * @param column - the already-trusted SQL column reference (`s.workspace`).
+ * @param workspace - the requested workspace filter.
+ * @returns the clause and its bindings, or undefined when the filter is absent.
+ */
+function workspaceClause(column, workspace) {
+    if (workspace === undefined || workspace === '')
+        return undefined;
+    if (workspace.endsWith('/')) {
+        return { clause: `${column} LIKE ? ESCAPE '\\'`, params: [`${escapeLike(workspace)}%`] };
+    }
+    return { clause: `${column} = ?`, params: [workspace] };
+}
+/** Escape a literal string for `RegExp`, so a query token is never read as a pattern. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Every case-insensitive occurrence of one term in one string. Case folding is done by the regex
+ * engine rather than by lowercasing the text: lowercasing can change a string's length, and the
+ * indices here are used to slice the ORIGINAL text.
+ * @param haystack - text to search.
+ * @param term - literal term to find.
+ * @returns non-overlapping spans in document order.
+ */
+function findSpans(haystack, term) {
+    if (term === '')
+        return [];
+    const spans = [];
+    for (const match of haystack.matchAll(new RegExp(escapeRegExp(term), 'gi'))) {
+        const start = match.index ?? 0;
+        spans.push({ start, end: start + match[0].length });
+    }
+    return spans;
+}
+/**
+ * Sort spans and merge the ones that touch, so adjacent matched terms render as one bracketed run
+ * (`[广告SDK]`) instead of a run of abutting brackets.
+ * @param spans - unmerged spans.
+ * @returns merged, ordered, non-overlapping spans.
+ */
+function mergeSpans(spans) {
+    const ordered = [...spans].sort((left, right) => left.start - right.start || left.end - right.end);
+    const merged = [];
+    for (const span of ordered) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && span.start <= last.end) {
+            if (span.end > last.end)
+                merged[merged.length - 1] = { start: last.start, end: span.end };
+            continue;
+        }
+        merged.push(span);
+    }
+    return merged;
+}
+/**
+ * The span the snippet window centres on: the longest query token that actually occurs in the entry,
+ * at its first occurrence. `highlightTerms` returns tokens longest-first, so the first term with a
+ * match is that longest term.
+ * @param text - the indexed entry text.
+ * @param terms - highlight terms, longest first.
+ * @returns the anchor span, or undefined when no term occurs literally.
+ */
+function anchorSpan(text, terms) {
+    for (const term of terms) {
+        const [first] = findSpans(text, term);
+        if (first !== undefined)
+            return first;
+    }
+    return undefined;
+}
+/**
+ * Cut a bounded excerpt around the first match and bracket every matched term inside it.
+ *
+ * The excerpt itself is at most `maxChars`; the brackets are added afterwards (and are not counted
+ * against the cap, so they never shorten what the caller sees). `clipped` reports that the excerpt
+ * is a window onto a longer entry, which is what the result's `truncated` flag needs to know.
+ * @param text - the full indexed entry text.
+ * @param terms - highlight terms, longest first.
+ * @param maxChars - largest excerpt length, in code units.
+ * @returns the rendered snippet and whether it was clipped.
+ */
+function renderSnippet(text, terms, maxChars) {
+    const cap = Math.max(1, Math.floor(maxChars));
+    const anchor = anchorSpan(text, terms);
+    const anchorLength = anchor === undefined ? 0 : anchor.end - anchor.start;
+    // Centre the window on the match, then pull it back inside the string; both clamps matter when the
+    // match is near either edge.
+    let start = anchor === undefined ? 0 : anchor.start - Math.floor((cap - Math.min(anchorLength, cap)) / 2);
+    start = Math.max(0, Math.min(start, Math.max(0, text.length - cap)));
+    let end = Math.min(text.length, start + cap);
+    // A match longer than the cap (a long Latin token) cannot fit whole: show its start rather than a
+    // tail slice the caller would not connect to the query.
+    if (anchor !== undefined && anchor.end > end) {
+        start = anchor.start;
+        end = Math.min(text.length, anchor.start + cap);
+    }
+    const excerpt = text.slice(start, end);
+    const spans = mergeSpans(terms.flatMap(term => findSpans(excerpt, term)));
+    let snippet = '';
+    let cursor = 0;
+    for (const span of spans) {
+        snippet += `${excerpt.slice(cursor, span.start)}[${excerpt.slice(span.start, span.end)}]`;
+        cursor = span.end;
+    }
+    snippet += excerpt.slice(cursor);
+    return { snippet, clipped: start > 0 || end < text.length };
+}
+/**
+ * Full-text search across indexed history.
+ *
+ * Ordering is `bm25`, then newest, then entry id. `bm25` is chosen over plain recency because a
+ * search result list is read top-down and the caller wants the best match first, not merely the most
+ * recent one. Ranking alone is NOT a total order: equally scored rows (extremely common for short
+ * entries and bigram queries) come back in whatever order the scan produced, which would make
+ * `LIMIT`/`OFFSET` paging skip and duplicate rows between pages. Appending `e.time DESC, e.id ASC`
+ * supplies a deterministic total order without displacing relevance, since `entry.id` is unique and
+ * UNIQUE breaks every remaining tie. That is also why this is the one operation whose page order is
+ * stable across requests against an unchanged index.
+ * @param db - the open index connection.
+ * @param request - the search query.
+ * @param maxSnippetChars - largest excerpt the plugin will render per hit.
+ * @returns the page of hits, the pre-pagination total, and whether anything was cut.
+ */
+export function search(db, request, maxSnippetChars) {
+    const match = matchExpression(request.query);
+    // A query with no searchable token cannot match anything, and `entry_fts MATCH ''` is a syntax
+    // error rather than "zero rows"; the empty answer is the honest one.
+    if (match === undefined)
+        return { operation: 'search', hits: [], total: 0, truncated: false };
+    // An explicitly empty `kinds` list means "none of them", not "no filter": SQL `IN ()` is a syntax
+    // error, so the empty answer is also the only correct one.
+    if (request.kinds !== undefined && request.kinds.length === 0) {
+        return { operation: 'search', hits: [], total: 0, truncated: false };
+    }
+    const filters = ['entry_fts MATCH ?'];
+    const params = [match];
+    if (request.kinds !== undefined) {
+        filters.push(`e.kind IN (${request.kinds.map(() => '?').join(', ')})`);
+        params.push(...request.kinds);
+    }
+    const workspace = workspaceClause('s.workspace', request.workspace);
+    if (workspace !== undefined) {
+        filters.push(workspace.clause);
+        params.push(...workspace.params);
+    }
+    if (request.after !== undefined) {
+        filters.push('e.time >= ?');
+        params.push(request.after);
+    }
+    if (request.before !== undefined) {
+        filters.push('e.time <= ?');
+        params.push(request.before);
+    }
+    const from = `FROM entry_fts
+    JOIN entry e ON e.id = entry_fts.rowid
+    JOIN session s ON s.id = e.session_id
+    WHERE ${filters.join(' AND ')}`;
+    const total = count(db, `SELECT count(*) AS total ${from}`, params);
+    const limit = bound(request.limit);
+    const offset = bound(request.offset);
+    if (limit === 0) {
+        return { operation: 'search', hits: [], total, truncated: total > offset };
+    }
+    const found = rows(db, `SELECT e.session_id AS session_id, s.title AS title, s.workspace AS workspace,
+            e.time AS time, e.kind AS kind, e.seq AS seq, e.turn AS turn, e.text AS text
+       ${from}
+      ORDER BY bm25(entry_fts), e.time DESC, e.id ASC
+      LIMIT ? OFFSET ?`, [...params, limit, offset]);
+    const terms = highlightTerms(request.query);
+    let clipped = false;
+    const hits = found.map((row) => {
+        const value = row['text'];
+        if (typeof value !== 'string') {
+            throw new SessiongraphError('an indexed entry has a non-text "text"', 'SESSIONGRAPH_CORRUPT');
+        }
+        const rendered = renderSnippet(value, terms, maxSnippetChars);
+        if (rendered.clipped)
+            clipped = true;
+        return { ...toHitSubject(row), snippet: rendered.snippet, length: value.length };
+    });
+    return { operation: 'search', hits, total, truncated: total > offset + hits.length || clipped };
+}
+/** Read a `session.id` column, refusing anything that is not text. */
+function sessionIdOf(row) {
+    const value = row['id'];
+    if (typeof value !== 'string') {
+        throw new SessiongraphError('an indexed session has a non-text "id"', 'SESSIONGRAPH_CORRUPT');
+    }
+    return SessiongraphSessionId(value);
+}
+/**
+ * Resolve a full session id or an unambiguous prefix.
+ *
+ * An exact id always wins, even when it is also a prefix of another id, so a caller holding the real
+ * id is never told it is ambiguous. A prefix that matches several sessions raises
+ * `SESSIONGRAPH_NOT_FOUND` with the candidates listed: the seam has no "ambiguous" code, the
+ * caller's remedy is the same as for a miss (narrow the reference), and the message carries the
+ * information needed to do that.
+ * @param db - the open index connection.
+ * @param wanted - the requested id or prefix.
+ * @returns the one session id it names.
+ */
+function resolveSessionId(db, wanted) {
+    const reference = wanted.trim();
+    if (reference === '') {
+        throw new SessiongraphError('a session id must be a non-empty string', 'SESSIONGRAPH_NOT_FOUND');
+    }
+    const exact = rows(db, 'SELECT id FROM session WHERE id = ?', [reference])[0];
+    if (exact !== undefined)
+        return sessionIdOf(exact);
+    const candidates = rows(db, `SELECT id FROM session WHERE id LIKE ? ESCAPE '\\' ORDER BY last_at DESC, id ASC LIMIT 8`, [`${escapeLike(reference)}%`]);
+    if (candidates.length === 0) {
+        throw new SessiongraphError(`no indexed session matches "${reference}"`, 'SESSIONGRAPH_NOT_FOUND');
+    }
+    const [only] = candidates;
+    if (only !== undefined && candidates.length === 1)
+        return sessionIdOf(only);
+    const listing = candidates.map(row => sessionIdOf(row)).join(', ');
+    throw new SessiongraphError(`session prefix "${reference}" is ambiguous; it matches several sessions: ${listing}`, 'SESSIONGRAPH_NOT_FOUND');
+}
+/**
+ * Read one session's metadata, a page of its entries in the session's own chronological order, and
+ * the sessions delegated from it.
+ * @param db - the open index connection.
+ * @param request - the session query.
+ * @returns the session summary, entry page, children, and whether more entries exist.
+ */
+export function session(db, request) {
+    const id = resolveSessionId(db, request.sessionId);
+    const summaryRow = rows(db, `SELECT ${SESSION_COLUMNS} FROM session WHERE id = ?`, [id])[0];
+    if (summaryRow === undefined) {
+        // Unreachable unless the index is being rewritten between two statements; report it as a miss
+        // rather than fabricating a summary.
+        throw new SessiongraphError(`no indexed session matches "${request.sessionId}"`, 'SESSIONGRAPH_NOT_FOUND');
+    }
+    const summary = toSessionSummary(summaryRow);
+    const limit = bound(request.limit);
+    const offset = bound(request.offset);
+    const total = count(db, 'SELECT count(*) AS total FROM entry WHERE session_id = ?', [id]);
+    const entries = limit === 0
+        ? []
+        : rows(db, `SELECT ${ENTRY_COLUMNS} FROM entry WHERE session_id = ? ORDER BY seq ASC LIMIT ? OFFSET ?`, [id, limit, offset]).map(toEntry);
+    const children = rows(db, 'SELECT id FROM session WHERE parent_session = ? ORDER BY created_at ASC, id ASC', [id]).map(row => sessionIdOf(row));
+    return {
+        operation: 'session',
+        session: summary,
+        entries,
+        children,
+        truncated: total > offset + entries.length,
+    };
+}
+/**
+ * List sessions newest-first by last activity.
+ * @param db - the open index connection.
+ * @param request - the timeline query.
+ * @returns the page of session summaries and whether more exist.
+ */
+export function timeline(db, request) {
+    const limit = bound(request.limit);
+    if (limit === 0)
+        return { operation: 'timeline', sessions: [], truncated: false };
+    const filters = [];
+    const params = [];
+    const workspace = workspaceClause('s.workspace', request.workspace);
+    if (workspace !== undefined) {
+        filters.push(workspace.clause);
+        params.push(...workspace.params);
+    }
+    // `after`/`before` describe the session's span, not an entry's time: `after` is "still active at or
+    // after", `before` is "already started at or before", so a call can ask for sessions alive in a
+    // window without knowing their internal event ordering.
+    if (request.after !== undefined) {
+        filters.push('s.last_at >= ?');
+        params.push(request.after);
+    }
+    if (request.before !== undefined) {
+        filters.push('s.created_at <= ?');
+        params.push(request.before);
+    }
+    const where = filters.length === 0 ? '' : `WHERE ${filters.join(' AND ')}`;
+    // One extra row distinguishes "exactly `limit` sessions" from "there are more" without a second
+    // count query.
+    const found = rows(db, `SELECT ${SESSION_COLUMNS} FROM session s ${where} ORDER BY s.last_at DESC, s.id ASC LIMIT ?`, [...params, limit + 1]);
+    const truncated = found.length > limit;
+    return {
+        operation: 'timeline',
+        sessions: (truncated ? found.slice(0, limit) : found).map(toSessionSummary),
+        truncated,
+    };
+}
+/**
+ * Enumerate indexed workspaces, most recently active first.
+ * @param db - the open index connection.
+ * @param request - the workspaces query.
+ * @returns the page of workspace statistics and the pre-limit total.
+ */
+export function workspaces(db, request) {
+    const total = count(db, 'SELECT count(DISTINCT workspace) AS total FROM session');
+    const limit = bound(request.limit);
+    if (limit === 0)
+        return { operation: 'workspaces', workspaces: [], total };
+    const found = rows(db, `SELECT workspace,
+            count(*) AS sessions,
+            COALESCE(sum(entries), 0) AS entries,
+            min(created_at) AS first_at,
+            max(last_at) AS last_at
+       FROM session
+      GROUP BY workspace
+      ORDER BY max(last_at) DESC, workspace ASC
+      LIMIT ?`, [limit]).map(toWorkspaceStat);
+    return { operation: 'workspaces', workspaces: found, total };
+}
+/**
+ * Report the index's own state.
+ *
+ * This is the one operation that answers when no index exists: a caller that never indexed anything
+ * needs to learn that fact, and every other operation fails loud instead of pretending the store is
+ * empty. A file that exists but cannot be read is still `SESSIONGRAPH_CORRUPT` — `indexes()` already
+ * claimed the root, so quietly downgrading it to "not indexed" would hide a damaged index.
+ * @param pool - the store's connection pool.
+ * @param indexRoot - directory the seam routed the request to.
+ * @returns the index summary, or the zero result for a root that holds no index.
+ */
+export function status(pool, indexRoot) {
+    const indexPath = databasePath(indexRoot);
+    let bytes = 0;
+    try {
+        bytes = statSync(indexPath).size;
+    }
+    catch {
+        return {
+            operation: 'status',
+            indexed: false,
+            indexPath,
+            sessions: 0,
+            liveSessions: 0,
+            entries: 0,
+            workspaces: 0,
+            indexedAt: undefined,
+            bytes: 0,
+        };
+    }
+    const db = pool.acquire(indexRoot);
+    const indexedAtRow = rows(db, 'SELECT value FROM meta WHERE key = ?', [META_INDEXED_AT])[0];
+    const raw = indexedAtRow?.['value'];
+    const parsed = typeof raw === 'string' ? Number(raw) : typeof raw === 'number' ? raw : Number.NaN;
+    return {
+        operation: 'status',
+        indexed: true,
+        indexPath,
+        sessions: count(db, 'SELECT count(*) AS total FROM session'),
+        liveSessions: count(db, `SELECT count(*) AS total FROM session WHERE source_path LIKE '${LIVE_SOURCE_LIKE}'`),
+        entries: count(db, 'SELECT count(*) AS total FROM entry'),
+        workspaces: count(db, 'SELECT count(DISTINCT workspace) AS total FROM session'),
+        // Epoch milliseconds fit a double, so a valid `indexed_at` never loses precision here; a missing
+        // or non-numeric stamp reads as "never run" rather than as 0 (i.e. 1970).
+        indexedAt: Number.isFinite(parsed) ? parsed : undefined,
+        bytes,
+    };
+}
+//# sourceMappingURL=queries.js.map

package/lib/rows.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Durable-boundary mapping from SQLite rows to seam records. Every value crossing this module comes
+ * from a file an independently versioned indexer wrote, so each field is checked before it becomes
+ * a typed record; a row that violates the format fails loud as `SESSIONGRAPH_CORRUPT` rather than
+ * reaching a consumer as a plausible-looking wrong value.
+ *
+ * Optional columns (`title`, `turn`, `parent_session`, `origin`, `agent_preset`) become `undefined`,
+ * never `null`: the seam's contract is a TypeScript `string | number | undefined`, and a leaked
+ * `null` would render as the literal text "null" one layer up.
+ * @module dsh-plugin-sessiongraph-sqlite/rows
+ */
+import type { SessiongraphEntry, SessiongraphHit, SessiongraphSessionSummary, SessiongraphWorkspaceStat } from 'dsh-plugin-sessiongraph-service';
+/** One row as `node:sqlite` returns it, before validation. */
+export type IndexRow = Record<string, unknown>;
+/**
+ * Build a {@link SessiongraphSessionSummary} from a `session` row.
+ * @param row - the raw row, selected with every column the summary reads.
+ * @returns the validated session record.
+ */
+export declare function toSessionSummary(row: IndexRow): SessiongraphSessionSummary;
+/**
+ * Build a {@link SessiongraphEntry} from an `entry` row.
+ * @param row - the raw row selected as `seq, time, kind, turn, text, clipped`.
+ * @returns the validated entry record.
+ */
+export declare function toEntry(row: IndexRow): SessiongraphEntry;
+/**
+ * Build the metadata half of a {@link SessiongraphHit}; the caller adds the rendered `snippet` and
+ * the entry's full `length`, because both are a function of the query and the plugin's snippet cap
+ * rather than of the stored row.
+ * @param row - the raw row selected as `session_id, title, workspace, time, kind, seq, turn`.
+ * @returns the validated hit fields.
+ */
+export declare function toHitSubject(row: IndexRow): Omit<SessiongraphHit, 'snippet' | 'length'>;
+/**
+ * Build a {@link SessiongraphWorkspaceStat} from a grouped `session` row.
+ * @param row - the raw row selected as `workspace, sessions, entries, first_at, last_at`.
+ * @returns the validated workspace record.
+ */
+export declare function toWorkspaceStat(row: IndexRow): SessiongraphWorkspaceStat;
+//# sourceMappingURL=rows.d.ts.map

package/lib/rows.js

@@ -0,0 +1,170 @@
+/**
+ * Durable-boundary mapping from SQLite rows to seam records. Every value crossing this module comes
+ * from a file an independently versioned indexer wrote, so each field is checked before it becomes
+ * a typed record; a row that violates the format fails loud as `SESSIONGRAPH_CORRUPT` rather than
+ * reaching a consumer as a plausible-looking wrong value.
+ *
+ * Optional columns (`title`, `turn`, `parent_session`, `origin`, `agent_preset`) become `undefined`,
+ * never `null`: the seam's contract is a TypeScript `string | number | undefined`, and a leaked
+ * `null` would render as the literal text "null" one layer up.
+ * @module dsh-plugin-sessiongraph-sqlite/rows
+ */
+import { SESSIONGRAPH_ENTRY_KINDS, SessiongraphError, SessiongraphSessionId, } from 'dsh-plugin-sessiongraph-service';
+/**
+ * Read a required text column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's string value.
+ */
+function text(row, column, what) {
+    const value = row[column];
+    if (typeof value !== 'string') {
+        throw new SessiongraphError(`${what} has a non-text "${column}"`, 'SESSIONGRAPH_CORRUPT');
+    }
+    return value;
+}
+/**
+ * Read a required integer column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's numeric value.
+ */
+function integer(row, column, what) {
+    const value = row[column];
+    if (typeof value === 'number')
+        return value;
+    // A stored INTEGER outside the safe range never reaches here: `node:sqlite` raises a RangeError
+    // while reading the row, because this store opens connections without bigint reads.
+    throw new SessiongraphError(`${what} has a non-integer "${column}"`, 'SESSIONGRAPH_CORRUPT');
+}
+/**
+ * Read an optional text column, treating SQL NULL and the empty string alike as absent.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's string value, or undefined when absent.
+ */
+function optionalText(row, column, what) {
+    const value = row[column];
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new SessiongraphError(`${what} has a non-text "${column}"`, 'SESSIONGRAPH_CORRUPT');
+    }
+    return value;
+}
+/**
+ * Read an optional integer column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's numeric value, or undefined when NULL.
+ */
+function optionalInteger(row, column, what) {
+    const value = row[column];
+    if (value === null || value === undefined)
+        return undefined;
+    return integer(row, column, what);
+}
+/**
+ * Read a boolean stored as INTEGER 0/1.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns whether the flag is set.
+ */
+function flag(row, column, what) {
+    return integer(row, column, what) !== 0;
+}
+/**
+ * Read an entry kind, refusing a value this schema version does not define.
+ * @param row - the raw row.
+ * @param what - the record being built, for the failure message.
+ * @returns the validated kind.
+ */
+function entryKind(row, what) {
+    const value = text(row, 'kind', what);
+    if (!SESSIONGRAPH_ENTRY_KINDS.includes(value)) {
+        throw new SessiongraphError(`${what} has an unknown entry kind "${value}"`, 'SESSIONGRAPH_CORRUPT');
+    }
+    return value;
+}
+/**
+ * Build a {@link SessiongraphSessionSummary} from a `session` row.
+ * @param row - the raw row, selected with every column the summary reads.
+ * @returns the validated session record.
+ */
+export function toSessionSummary(row) {
+    const what = 'an indexed session';
+    const id = text(row, 'id', what);
+    const named = `indexed session "${id}"`;
+    const title = optionalText(row, 'title', named);
+    const parentSession = optionalText(row, 'parent_session', named);
+    const origin = optionalText(row, 'origin', named);
+    const agentPreset = optionalText(row, 'agent_preset', named);
+    return {
+        sessionId: SessiongraphSessionId(id),
+        title,
+        workspace: text(row, 'workspace', named),
+        createdAt: integer(row, 'created_at', named),
+        lastAt: integer(row, 'last_at', named),
+        turns: integer(row, 'turns', named),
+        entries: integer(row, 'entries', named),
+        parentSession,
+        origin,
+        agentPreset,
+    };
+}
+/**
+ * Build a {@link SessiongraphEntry} from an `entry` row.
+ * @param row - the raw row selected as `seq, time, kind, turn, text, clipped`.
+ * @returns the validated entry record.
+ */
+export function toEntry(row) {
+    const what = 'an indexed entry';
+    return {
+        seq: integer(row, 'seq', what),
+        time: integer(row, 'time', what),
+        kind: entryKind(row, what),
+        turn: optionalInteger(row, 'turn', what),
+        text: text(row, 'text', what),
+        clipped: flag(row, 'clipped', what),
+    };
+}
+/**
+ * Build the metadata half of a {@link SessiongraphHit}; the caller adds the rendered `snippet` and
+ * the entry's full `length`, because both are a function of the query and the plugin's snippet cap
+ * rather than of the stored row.
+ * @param row - the raw row selected as `session_id, title, workspace, time, kind, seq, turn`.
+ * @returns the validated hit fields.
+ */
+export function toHitSubject(row) {
+    const what = 'a search hit';
+    return {
+        sessionId: SessiongraphSessionId(text(row, 'session_id', what)),
+        title: optionalText(row, 'title', what),
+        workspace: text(row, 'workspace', what),
+        time: integer(row, 'time', what),
+        kind: entryKind(row, what),
+        seq: integer(row, 'seq', what),
+        turn: optionalInteger(row, 'turn', what),
+    };
+}
+/**
+ * Build a {@link SessiongraphWorkspaceStat} from a grouped `session` row.
+ * @param row - the raw row selected as `workspace, sessions, entries, first_at, last_at`.
+ * @returns the validated workspace record.
+ */
+export function toWorkspaceStat(row) {
+    const what = 'an indexed workspace';
+    return {
+        workspace: text(row, 'workspace', what),
+        sessions: integer(row, 'sessions', what),
+        entries: integer(row, 'entries', what),
+        firstAt: integer(row, 'first_at', what),
+        lastAt: integer(row, 'last_at', what),
+    };
+}
+//# sourceMappingURL=rows.js.map

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "dsh-plugin-sessiongraph-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Read-only SQLite store for the DeepSeek Harness session-graph seam — answers search/session/timeline/workspaces/status from the on-disk index at <indexRoot>/index.db without ever writing to it",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "session",
+    "session-history",
+    "search",
+    "fts",
+    "bigram",
+    "sqlite",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "CC ZHAO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CC19990113/dsh-plugin-sessiongraph.git",
+    "directory": "packages/sqlite"
+  },
+  "homepage": "https://github.com/CC19990113/dsh-plugin-sessiongraph#readme",
+  "bugs": "https://github.com/CC19990113/dsh-plugin-sessiongraph/issues",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "dsh-plugin-sessiongraph-service": "^0.1.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-invariants": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.