dsh-plugin-sessiongraph-service 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/assert.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A three-line re-statement of `assertNever`, owned here instead of imported from the host.
+ *
+ * `@deepseek-ai/dsh-llm` exported this through 0.1.x and dropped it in 0.2.x (the implementation
+ * moved to `@deepseek-ai/dsh-util-values`, which 0.1.x does not ship). A static import of a symbol
+ * the host no longer exports parses fine and fails at load, which removes the whole consumer plugin
+ * from the host instead of failing at one unreachable branch.
+ * @module dsh-plugin-sessiongraph-service/assert
+ */
+/**
+ * Compile-time exhaustiveness check for a discriminated union.
+ * @param value - the value that must never be reached.
+ * @returns never; throws when the value is actually reachable.
+ */
+export declare function assertNever(value: never): never;
+//# sourceMappingURL=assert.d.ts.map

package/lib/assert.js

@@ -0,0 +1,18 @@
+/**
+ * A three-line re-statement of `assertNever`, owned here instead of imported from the host.
+ *
+ * `@deepseek-ai/dsh-llm` exported this through 0.1.x and dropped it in 0.2.x (the implementation
+ * moved to `@deepseek-ai/dsh-util-values`, which 0.1.x does not ship). A static import of a symbol
+ * the host no longer exports parses fine and fails at load, which removes the whole consumer plugin
+ * from the host instead of failing at one unreachable branch.
+ * @module dsh-plugin-sessiongraph-service/assert
+ */
+/**
+ * Compile-time exhaustiveness check for a discriminated union.
+ * @param value - the value that must never be reached.
+ * @returns never; throws when the value is actually reachable.
+ */
+export function assertNever(value) {
+    throw new Error(`unreachable: ${JSON.stringify(value)}`);
+}
+//# sourceMappingURL=assert.js.map

package/lib/brand.d.ts

@@ -0,0 +1,49 @@
+/**
+ * dsh-plugin-sessiongraph's owned branded ids: {@link SessiongraphStoreId}, the identity a read
+ * provider reserves on `ctx.sessiongraph`; {@link SessiongraphIndexerId}, the identity a write
+ * provider reserves; and {@link SessiongraphSessionId}, a harness session id taken verbatim from a
+ * session log's header.
+ *
+ * The brand is declared here rather than borrowed from `@deepseek-ai/dsh-brand` on purpose: a host
+ * utility that exists in one DSH line and not another turns into a load-time failure that removes
+ * the whole plugin, which is exactly the failure mode a four-line `unique symbol` avoids. Keeping
+ * each type with its factory lets `index.ts` re-export all three under one name.
+ * @module dsh-plugin-sessiongraph-service/brand
+ */
+declare const SESSIONGRAPH_STORE_BRAND: unique symbol;
+declare const SESSIONGRAPH_INDEXER_BRAND: unique symbol;
+declare const SESSIONGRAPH_SESSION_BRAND: unique symbol;
+/** Opaque store-provider identity, reserved at registration and released by the disposer. */
+export type SessiongraphStoreId = string & {
+    readonly [SESSIONGRAPH_STORE_BRAND]: true;
+};
+/**
+ * Brand a string as a {@link SessiongraphStoreId}. No validation — the registry rejects an empty id
+ * at registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export declare function SessiongraphStoreId(id: string): SessiongraphStoreId;
+/** Opaque indexer-provider identity, reserved at registration and released by the disposer. */
+export type SessiongraphIndexerId = string & {
+    readonly [SESSIONGRAPH_INDEXER_BRAND]: true;
+};
+/**
+ * Brand a string as a {@link SessiongraphIndexerId}. No validation — the registry rejects an empty id
+ * at registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export declare function SessiongraphIndexerId(id: string): SessiongraphIndexerId;
+/** Identity of one harness session, as recorded in its log header. */
+export type SessiongraphSessionId = string & {
+    readonly [SESSIONGRAPH_SESSION_BRAND]: true;
+};
+/**
+ * Brand a string as a {@link SessiongraphSessionId}.
+ * @param id - the session id read from a session log header.
+ * @returns the same string, branded.
+ */
+export declare function SessiongraphSessionId(id: string): SessiongraphSessionId;
+export {};
+//# sourceMappingURL=brand.d.ts.map

package/lib/brand.js

@@ -0,0 +1,39 @@
+/**
+ * dsh-plugin-sessiongraph's owned branded ids: {@link SessiongraphStoreId}, the identity a read
+ * provider reserves on `ctx.sessiongraph`; {@link SessiongraphIndexerId}, the identity a write
+ * provider reserves; and {@link SessiongraphSessionId}, a harness session id taken verbatim from a
+ * session log's header.
+ *
+ * The brand is declared here rather than borrowed from `@deepseek-ai/dsh-brand` on purpose: a host
+ * utility that exists in one DSH line and not another turns into a load-time failure that removes
+ * the whole plugin, which is exactly the failure mode a four-line `unique symbol` avoids. Keeping
+ * each type with its factory lets `index.ts` re-export all three under one name.
+ * @module dsh-plugin-sessiongraph-service/brand
+ */
+/**
+ * Brand a string as a {@link SessiongraphStoreId}. No validation — the registry rejects an empty id
+ * at registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export function SessiongraphStoreId(id) {
+    return id;
+}
+/**
+ * Brand a string as a {@link SessiongraphIndexerId}. No validation — the registry rejects an empty id
+ * at registration.
+ * @param id - the provider's stable identifier.
+ * @returns the same string, branded.
+ */
+export function SessiongraphIndexerId(id) {
+    return id;
+}
+/**
+ * Brand a string as a {@link SessiongraphSessionId}.
+ * @param id - the session id read from a session log header.
+ * @returns the same string, branded.
+ */
+export function SessiongraphSessionId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Service Definition for the session-graph capability seam (`ctx.sessiongraph`): a store-provider
+ * and indexer-provider registry over local conversation history, plus the normalized query
+ * vocabulary — `search`, `session`, `timeline`, `workspaces`, and `status`.
+ *
+ * A store reserves a branded id at registration and declares which index roots it can serve through
+ * {@link SessiongraphStoreProvider.indexes}. Selection asks every registered store per query and
+ * requires exactly one claimant, so registration and hot-reload order never change routing; zero
+ * claimants and several claimants are both loud failures rather than a silent pick. The seam carries
+ * no session text and performs no filesystem access of its own.
+ *
+ * Unlike the code-graph seam, `status` is answerable without an index: a caller that has never
+ * indexed anything needs to learn that fact, and every other operation throws
+ * `SESSIONGRAPH_UNAVAILABLE` instead of pretending the store is empty.
+ * @module dsh-plugin-sessiongraph-service
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { SessiongraphIndexer, SessiongraphIndexOptions, SessiongraphIndexReport, SessiongraphRequest, SessiongraphResultFor, SessiongraphService, SessiongraphStoreProvider } from './types.ts';
+export { assertNever } from './assert.ts';
+export { SessiongraphIndexerId, SessiongraphSessionId, SessiongraphStoreId } from './brand.ts';
+export { ENTRY_FTS_TABLE, ENTRY_TABLE, INDEX_RELATIVE_PATH, META_DISCOVERED, META_FAILED, META_INDEXED_AT, META_SCHEMA_VERSION, SCHEMA_STATEMENTS, SCHEMA_VERSION, SESSION_TABLE, } from './schema.ts';
+export { highlightTerms, isCjk, matchExpression, tokenize } from './tokenize.ts';
+export { SessiongraphError } from './types.ts';
+export type { SessiongraphEntry, SessiongraphEntryKind, SessiongraphErrorCode, SessiongraphHit, SessiongraphIndexer, SessiongraphIndexOptions, SessiongraphIndexReport, SessiongraphOperation, SessiongraphRequest, SessiongraphRequestBase, SessiongraphResult, SessiongraphResultFor, SessiongraphSearchRequest, SessiongraphSearchResult, SessiongraphService, SessiongraphSessionRequest, SessiongraphSessionResult, SessiongraphSessionSummary, SessiongraphStatusRequest, SessiongraphStatusResult, SessiongraphStoreProvider, SessiongraphTimelineRequest, SessiongraphTimelineResult, SessiongraphWorkspaceStat, SessiongraphWorkspacesRequest, SessiongraphWorkspacesResult, } from './types.ts';
+export { SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_OPERATIONS } from './types.ts';
+/**
+ * `ctx.sessiongraph`. Holds the store and indexer reservations; selection reads them per call so a
+ * provider that unloads mid-session stops serving without leaving a stale route behind.
+ */
+export declare class Sessiongraph extends Service implements SessiongraphService {
+    private readonly stores;
+    private readonly indexers;
+    constructor(ctx: Context);
+    registerStore(provider: SessiongraphStoreProvider): () => void;
+    registerIndexer(provider: SessiongraphIndexer): () => void;
+    available(indexRoot: string, signal?: AbortSignal): Promise<boolean>;
+    query<R extends SessiongraphRequest>(request: R, signal?: AbortSignal): Promise<SessiongraphResultFor<R>>;
+    index(indexRoot: string, options?: SessiongraphIndexOptions, signal?: AbortSignal): Promise<SessiongraphIndexReport>;
+    /**
+     * The one store that serves `indexRoot`. Every registered store is asked concurrently, so the
+     * answer does not depend on registration order; zero and several claimants both throw.
+     * @param indexRoot - directory the request targets.
+     * @param signal - aborts the availability checks.
+     * @returns the single claiming store.
+     */
+    private select;
+    /**
+     * The one indexer that can build `indexRoot`. Same one-claimant rule as {@link Sessiongraph.select}.
+     * @param indexRoot - directory to build into.
+     * @param signal - aborts the availability checks.
+     * @returns the single claiming indexer.
+     */
+    private selectIndexer;
+}
+export default Sessiongraph;
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "sessiongraph";
+/**
+ * Publish the seam. Registers nothing else: providers arrive from their own plugins, which is what
+ * lets a deployment swap the store or the indexer without touching the model-facing tool.
+ * @param ctx - Cordis context to install into.
+ */
+export declare function apply(ctx: Context): void;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The session-graph seam. Present whenever this package's plugin is loaded. */
+        sessiongraph: SessiongraphService;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,173 @@
+/**
+ * Service Definition for the session-graph capability seam (`ctx.sessiongraph`): a store-provider
+ * and indexer-provider registry over local conversation history, plus the normalized query
+ * vocabulary — `search`, `session`, `timeline`, `workspaces`, and `status`.
+ *
+ * A store reserves a branded id at registration and declares which index roots it can serve through
+ * {@link SessiongraphStoreProvider.indexes}. Selection asks every registered store per query and
+ * requires exactly one claimant, so registration and hot-reload order never change routing; zero
+ * claimants and several claimants are both loud failures rather than a silent pick. The seam carries
+ * no session text and performs no filesystem access of its own.
+ *
+ * Unlike the code-graph seam, `status` is answerable without an index: a caller that has never
+ * indexed anything needs to learn that fact, and every other operation throws
+ * `SESSIONGRAPH_UNAVAILABLE` instead of pretending the store is empty.
+ * @module dsh-plugin-sessiongraph-service
+ */
+import { join } from 'node:path';
+import { Service } from '@deepseek-ai/cordis';
+import { INDEX_RELATIVE_PATH } from "./schema.js";
+import { SessiongraphError } from "./types.js";
+export { assertNever } from "./assert.js";
+export { SessiongraphIndexerId, SessiongraphSessionId, SessiongraphStoreId } from "./brand.js";
+export { ENTRY_FTS_TABLE, ENTRY_TABLE, INDEX_RELATIVE_PATH, META_DISCOVERED, META_FAILED, META_INDEXED_AT, META_SCHEMA_VERSION, SCHEMA_STATEMENTS, SCHEMA_VERSION, SESSION_TABLE, } from "./schema.js";
+export { highlightTerms, isCjk, matchExpression, tokenize } from "./tokenize.js";
+export { SessiongraphError } from "./types.js";
+export { SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_OPERATIONS } from "./types.js";
+/**
+ * `ctx.sessiongraph`. Holds the store and indexer reservations; selection reads them per call so a
+ * provider that unloads mid-session stops serving without leaving a stale route behind.
+ */
+export class Sessiongraph extends Service {
+    stores = new Map();
+    indexers = new Map();
+    constructor(ctx) {
+        super(ctx, 'sessiongraph');
+    }
+    registerStore(provider) {
+        const id = provider.id;
+        if (id.trim() === '') {
+            throw new SessiongraphError('a session-graph store id must be a non-empty string', 'SESSIONGRAPH_INVALID_PROVIDER');
+        }
+        if (this.stores.has(id)) {
+            throw new SessiongraphError(`a session-graph store with id "${id}" is already registered`, 'SESSIONGRAPH_CONFLICT');
+        }
+        const dispose = this.ctx.effect(function* () {
+            this.stores.set(id, provider);
+            yield () => {
+                this.stores.delete(id);
+            };
+        }.bind(this), 'sessiongraph.registerStore()');
+        return () => void dispose();
+    }
+    registerIndexer(provider) {
+        const id = provider.id;
+        if (id.trim() === '') {
+            throw new SessiongraphError('a session-graph indexer id must be a non-empty string', 'SESSIONGRAPH_INVALID_PROVIDER');
+        }
+        if (this.indexers.has(id)) {
+            throw new SessiongraphError(`a session-graph indexer with id "${id}" is already registered`, 'SESSIONGRAPH_CONFLICT');
+        }
+        const dispose = this.ctx.effect(function* () {
+            this.indexers.set(id, provider);
+            yield () => {
+                this.indexers.delete(id);
+            };
+        }.bind(this), 'sessiongraph.registerIndexer()');
+        return () => void dispose();
+    }
+    async available(indexRoot, signal) {
+        if (this.stores.size === 0)
+            return false;
+        const candidates = [...this.stores.values()];
+        const claims = await Promise.all(candidates.map(store => store.indexes(indexRoot, signal)));
+        return claims.some(Boolean);
+    }
+    async query(request, signal) {
+        // `status` is the one operation answerable with nothing indexed: a caller whose root has no
+        // store claim needs to learn *that fact*, not receive the same unavailable error every other
+        // operation raises. A conflict is still a real error — two stores claiming one root is a
+        // deployment mistake, and silently reporting "not indexed" would hide it.
+        let store;
+        try {
+            store = await this.select(request.indexRoot, signal);
+        }
+        catch (error) {
+            if (request.operation === 'status' && error instanceof SessiongraphError && error.code === 'SESSIONGRAPH_UNAVAILABLE') {
+                return emptyStatus(request.indexRoot);
+            }
+            throw error;
+        }
+        return store.query(request, signal);
+    }
+    async index(indexRoot, options = {}, signal) {
+        const indexer = await this.selectIndexer(indexRoot, signal);
+        return indexer.index(indexRoot, options, signal);
+    }
+    /**
+     * The one store that serves `indexRoot`. Every registered store is asked concurrently, so the
+     * answer does not depend on registration order; zero and several claimants both throw.
+     * @param indexRoot - directory the request targets.
+     * @param signal - aborts the availability checks.
+     * @returns the single claiming store.
+     */
+    async select(indexRoot, signal) {
+        const candidates = [...this.stores.values()];
+        if (candidates.length === 0) {
+            throw new SessiongraphError('no session-graph store is registered', 'SESSIONGRAPH_UNAVAILABLE');
+        }
+        const claims = await Promise.all(candidates.map(store => store.indexes(indexRoot, signal)));
+        const claimants = candidates.filter((_, index) => claims[index]);
+        const [only, rival] = claimants;
+        if (only === undefined) {
+            throw new SessiongraphError(`no session-graph store indexes "${indexRoot}"`, 'SESSIONGRAPH_UNAVAILABLE');
+        }
+        if (rival !== undefined) {
+            const ids = claimants.map(store => store.id).join(', ');
+            throw new SessiongraphError(`several session-graph stores index "${indexRoot}": ${ids}`, 'SESSIONGRAPH_CONFLICT');
+        }
+        return only;
+    }
+    /**
+     * The one indexer that can build `indexRoot`. Same one-claimant rule as {@link Sessiongraph.select}.
+     * @param indexRoot - directory to build into.
+     * @param signal - aborts the availability checks.
+     * @returns the single claiming indexer.
+     */
+    async selectIndexer(indexRoot, signal) {
+        const candidates = [...this.indexers.values()];
+        if (candidates.length === 0) {
+            throw new SessiongraphError('no session-graph indexer is registered', 'SESSIONGRAPH_UNAVAILABLE');
+        }
+        const claims = await Promise.all(candidates.map(indexer => indexer.canIndex(indexRoot, signal)));
+        const claimants = candidates.filter((_, index) => claims[index]);
+        const [only, rival] = claimants;
+        if (only === undefined) {
+            throw new SessiongraphError(`no session-graph indexer can index "${indexRoot}"`, 'SESSIONGRAPH_UNAVAILABLE');
+        }
+        if (rival !== undefined) {
+            const ids = claimants.map(indexer => indexer.id).join(', ');
+            throw new SessiongraphError(`several session-graph indexers can index "${indexRoot}": ${ids}`, 'SESSIONGRAPH_CONFLICT');
+        }
+        return only;
+    }
+}
+export default Sessiongraph;
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'sessiongraph';
+/**
+ * Publish the seam. Registers nothing else: providers arrive from their own plugins, which is what
+ * lets a deployment swap the store or the indexer without touching the model-facing tool.
+ * @param ctx - Cordis context to install into.
+ */
+export function apply(ctx) {
+    ctx.plugin(Sessiongraph);
+}
+/**
+ * The zero-value status a root with no store claim reports: the index has never been built.
+ * @param indexRoot - directory the caller asked about.
+ * @returns a status result shaped exactly like a store's own, with nothing indexed.
+ */
+function emptyStatus(indexRoot) {
+    return {
+        operation: 'status',
+        indexed: false,
+        indexPath: join(indexRoot, INDEX_RELATIVE_PATH),
+        sessions: 0,
+        entries: 0,
+        workspaces: 0,
+        indexedAt: undefined,
+        bytes: 0,
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-sessiongraph-service`.
+ * @module dsh-plugin-sessiongraph-service/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sessiongraph-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-service`.
+ * @module dsh-plugin-sessiongraph-service/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-sessiongraph-service';
+/** Cordis companion plugin name. */
+export const name = 'sessiongraph-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: store and indexer reservations are private state resolved per call, and the
+ * seam emits no lifecycle event and exposes no enumerable snapshot to compare an owned relation
+ * against.
+ */
+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/schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The on-disk schema both providers agree on. The indexer writes it; the store reads it. It lives in
+ * the seam package precisely so neither provider can drift from the other without editing this file.
+ *
+ * The format is ours to evolve: `SCHEMA_VERSION` is stamped into `meta`, and a store refuses a file
+ * whose version it does not know rather than guessing at a shape. That is deliberately stricter than
+ * "read whatever is there" — a mismatch must surface as a loud {@link SessiongraphError}, not as a
+ * silently empty result that looks like "no match".
+ * @module dsh-plugin-sessiongraph-service/schema
+ */
+/** Current on-disk schema version. Bump on any change to {@link SCHEMA_STATEMENTS}. */
+export declare const SCHEMA_VERSION = 1;
+/** Relative path of the index file inside an index root. */
+export declare const INDEX_RELATIVE_PATH = "index.db";
+/** One session, keyed by its harness session id. */
+export declare const SESSION_TABLE = "session";
+/** One searchable entry inside a session. */
+export declare const ENTRY_TABLE = "entry";
+/** The FTS5 virtual table over `entry`, with `entry.id` as its `rowid`. */
+export declare const ENTRY_FTS_TABLE = "entry_fts";
+/**
+ * Every statement needed to create an index from nothing, in dependency order.
+ *
+ * `entry_fts` is an external-content-free FTS5 table: it stores only the bigram token stream and
+ * keys rows by `entry.id`, so the entry text is never duplicated into the index. `content=''` would
+ * also work, but the plain form keeps `delete`/`insert` symmetrical with one rowid.
+ */
+export declare const SCHEMA_STATEMENTS: readonly string[];
+/** `meta` keys the store and the indexer exchange through the file. */
+export declare const META_SCHEMA_VERSION = "schema_version";
+/** Epoch milliseconds of the last completed index run. */
+export declare const META_INDEXED_AT = "indexed_at";
+/** Number of source sessions the last run discovered. */
+export declare const META_DISCOVERED = "discovered";
+/** Number of source sessions the last run could not parse. */
+export declare const META_FAILED = "failed";
+//# sourceMappingURL=schema.d.ts.map

package/lib/schema.js

@@ -0,0 +1,74 @@
+/**
+ * The on-disk schema both providers agree on. The indexer writes it; the store reads it. It lives in
+ * the seam package precisely so neither provider can drift from the other without editing this file.
+ *
+ * The format is ours to evolve: `SCHEMA_VERSION` is stamped into `meta`, and a store refuses a file
+ * whose version it does not know rather than guessing at a shape. That is deliberately stricter than
+ * "read whatever is there" — a mismatch must surface as a loud {@link SessiongraphError}, not as a
+ * silently empty result that looks like "no match".
+ * @module dsh-plugin-sessiongraph-service/schema
+ */
+/** Current on-disk schema version. Bump on any change to {@link SCHEMA_STATEMENTS}. */
+export const SCHEMA_VERSION = 1;
+/** Relative path of the index file inside an index root. */
+export const INDEX_RELATIVE_PATH = 'index.db';
+/** One session, keyed by its harness session id. */
+export const SESSION_TABLE = 'session';
+/** One searchable entry inside a session. */
+export const ENTRY_TABLE = 'entry';
+/** The FTS5 virtual table over `entry`, with `entry.id` as its `rowid`. */
+export const ENTRY_FTS_TABLE = 'entry_fts';
+/**
+ * Every statement needed to create an index from nothing, in dependency order.
+ *
+ * `entry_fts` is an external-content-free FTS5 table: it stores only the bigram token stream and
+ * keys rows by `entry.id`, so the entry text is never duplicated into the index. `content=''` would
+ * also work, but the plain form keeps `delete`/`insert` symmetrical with one rowid.
+ */
+export const SCHEMA_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS meta (
+     key TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${SESSION_TABLE} (
+     id TEXT PRIMARY KEY,
+     workspace TEXT NOT NULL,
+     title TEXT,
+     created_at INTEGER NOT NULL,
+     last_at INTEGER NOT NULL,
+     parent_session TEXT,
+     origin TEXT,
+     agent_preset TEXT,
+     turns INTEGER NOT NULL DEFAULT 0,
+     entries INTEGER NOT NULL DEFAULT 0,
+     source_path TEXT NOT NULL,
+     source_mtime INTEGER NOT NULL,
+     source_size INTEGER NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${ENTRY_TABLE} (
+     id INTEGER PRIMARY KEY,
+     session_id TEXT NOT NULL,
+     seq INTEGER NOT NULL,
+     time INTEGER NOT NULL,
+     turn INTEGER,
+     kind TEXT NOT NULL,
+     text TEXT NOT NULL,
+     clipped INTEGER NOT NULL DEFAULT 0
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_entry_session ON ${ENTRY_TABLE} (session_id, seq)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_last ON ${SESSION_TABLE} (last_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_workspace ON ${SESSION_TABLE} (workspace, last_at DESC)`,
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${ENTRY_FTS_TABLE} USING fts5(
+     tokens,
+     tokenize = 'unicode61 remove_diacritics 0'
+   )`,
+];
+/** `meta` keys the store and the indexer exchange through the file. */
+export const META_SCHEMA_VERSION = 'schema_version';
+/** Epoch milliseconds of the last completed index run. */
+export const META_INDEXED_AT = 'indexed_at';
+/** Number of source sessions the last run discovered. */
+export const META_DISCOVERED = 'discovered';
+/** Number of source sessions the last run could not parse. */
+export const META_FAILED = 'failed';
+//# sourceMappingURL=schema.js.map

package/lib/tokenize.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The one tokenizer both sides use: the indexer tokenizes an entry on write, the store tokenizes a
+ * query on read. Keeping them in the seam package is the whole point — a write-side and read-side
+ * tokenizer that drift by one rule produce an index that silently cannot answer its own queries.
+ *
+ * ## Why bigrams
+ *
+ * SQLite's `unicode61` tokenizer splits on characters that are neither alphanumeric nor `_`, and
+ * every CJK character is alphanumeric, so a whole Chinese sentence becomes ONE token: `广告` matches
+ * nothing in `我今天在改广告SDK`, verified against SQLite 3.50.4. FTS5's `trigram` tokenizer fixes
+ * three-or-more-character substrings but still misses the very common two-character Chinese word
+ * (`广告`, `域名`, `功率`). So Chinese runs are expanded into overlapping two-character tokens on
+ * BOTH sides: `广告点击` writes `广告 告点 点击`, and a query for `点击跳转` becomes
+ * `"点击" AND "跳转" AND ...`. Latin and digit runs stay whole words in lower case.
+ *
+ * The cost is a bigger token stream (roughly one token per Chinese character) and AND-semantics
+ * recall rather than exact phrase matching: `广告跳转` can match an entry where those characters are
+ * not adjacent. For "find the conversation where I talked about this", recall beats phrase fidelity,
+ * and a caller who needs adjacency can quote a longer term.
+ * @module dsh-plugin-sessiongraph-service/tokenize
+ */
+/**
+ * Tokenize text into the stream written to `entry_fts.tokens` and compared against a query.
+ *
+ * @param text - raw entry text or query text.
+ * @returns tokens in document order, with duplicates kept (FTS5 deduplicates per position itself).
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Build the FTS5 MATCH expression for a user query.
+ *
+ * Tokens are double-quoted (so FTS5 treats them as literals rather than barewords) and joined with
+ * `AND`, which is the OR-free form that keeps a multi-token query narrowing instead of widening.
+ *
+ * @param query - raw query text.
+ * @returns an FTS5 MATCH expression, or `undefined` when the query has no searchable token.
+ */
+export declare function matchExpression(query: string): string | undefined;
+/**
+ * Tokenize a query the way the index expects, deduplicated, for snippet highlighting.
+ * @param query - raw query text.
+ * @returns distinct tokens, longest first so a longer term claims the highlight before a bigram does.
+ */
+export declare function highlightTerms(query: string): string[];
+/**
+ * Whether a character is a CJK ideograph.
+ * @param char - one character.
+ * @returns true for an ideograph.
+ */
+export declare function isCjk(char: string): boolean;
+//# sourceMappingURL=tokenize.d.ts.map

package/lib/tokenize.js

@@ -0,0 +1,113 @@
+/**
+ * The one tokenizer both sides use: the indexer tokenizes an entry on write, the store tokenizes a
+ * query on read. Keeping them in the seam package is the whole point — a write-side and read-side
+ * tokenizer that drift by one rule produce an index that silently cannot answer its own queries.
+ *
+ * ## Why bigrams
+ *
+ * SQLite's `unicode61` tokenizer splits on characters that are neither alphanumeric nor `_`, and
+ * every CJK character is alphanumeric, so a whole Chinese sentence becomes ONE token: `广告` matches
+ * nothing in `我今天在改广告SDK`, verified against SQLite 3.50.4. FTS5's `trigram` tokenizer fixes
+ * three-or-more-character substrings but still misses the very common two-character Chinese word
+ * (`广告`, `域名`, `功率`). So Chinese runs are expanded into overlapping two-character tokens on
+ * BOTH sides: `广告点击` writes `广告 告点 点击`, and a query for `点击跳转` becomes
+ * `"点击" AND "跳转" AND ...`. Latin and digit runs stay whole words in lower case.
+ *
+ * The cost is a bigger token stream (roughly one token per Chinese character) and AND-semantics
+ * recall rather than exact phrase matching: `广告跳转` can match an entry where those characters are
+ * not adjacent. For "find the conversation where I talked about this", recall beats phrase fidelity,
+ * and a caller who needs adjacency can quote a longer term.
+ * @module dsh-plugin-sessiongraph-service/tokenize
+ */
+/** Longest Latin/digit run kept as one token before it is split on `_`/`-` boundaries. */
+const MAX_LATIN_TOKEN_LENGTH = 64;
+/** A CJK ideograph, including the extension-A block and the compatibility block. */
+const CJK = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+/** A run of one or more CJK ideographs. */
+const CJK_RUN = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]+/g;
+/**
+ * A run of Latin letters and digits. `_` deliberately does NOT belong to the run: FTS5's `unicode61`
+ * treats it as a separator, and a caller searching `codegraph` must still find an entry that says
+ * `codegraph_index`, so the write side splits on it exactly like the tokenizer would.
+ */
+const LATIN_RUN = /[A-Za-z0-9]+/g;
+/**
+ * Tokenize text into the stream written to `entry_fts.tokens` and compared against a query.
+ *
+ * @param text - raw entry text or query text.
+ * @returns tokens in document order, with duplicates kept (FTS5 deduplicates per position itself).
+ */
+export function tokenize(text) {
+    if (text === '')
+        return [];
+    const tokens = [];
+    // Walk the two character classes in one pass so a mixed string keeps its order; positions do not
+    // matter to the query, but a stable order keeps a written index byte-reproducible for tests.
+    const matched = [];
+    for (const match of text.matchAll(CJK_RUN)) {
+        matched.push({ at: match.index, value: bigrams(match[0]) });
+    }
+    for (const match of text.matchAll(LATIN_RUN)) {
+        const token = match[0].toLowerCase();
+        if (token.length === 0)
+            continue;
+        matched.push({ at: match.index, value: token.length > MAX_LATIN_TOKEN_LENGTH ? [token.slice(0, MAX_LATIN_TOKEN_LENGTH)] : [token] });
+    }
+    matched.sort((left, right) => left.at - right.at);
+    for (const entry of matched)
+        tokens.push(...entry.value);
+    return tokens;
+}
+/**
+ * Expand one CJK run into overlapping two-character tokens.
+ * @param run - a non-empty run of ideographs.
+ * @returns one token per character for a single character, else one per adjacent pair.
+ */
+function bigrams(run) {
+    if (run.length <= 1)
+        return [run];
+    const tokens = [];
+    for (let index = 0; index < run.length - 1; index += 1)
+        tokens.push(run.slice(index, index + 2));
+    return tokens;
+}
+/**
+ * Build the FTS5 MATCH expression for a user query.
+ *
+ * Tokens are double-quoted (so FTS5 treats them as literals rather than barewords) and joined with
+ * `AND`, which is the OR-free form that keeps a multi-token query narrowing instead of widening.
+ *
+ * @param query - raw query text.
+ * @returns an FTS5 MATCH expression, or `undefined` when the query has no searchable token.
+ */
+export function matchExpression(query) {
+    const tokens = dedupe(tokenize(query));
+    if (tokens.length === 0)
+        return undefined;
+    return tokens.map(token => `"${token.replaceAll('"', '""')}"`).join(' AND ');
+}
+/**
+ * Tokenize a query the way the index expects, deduplicated, for snippet highlighting.
+ * @param query - raw query text.
+ * @returns distinct tokens, longest first so a longer term claims the highlight before a bigram does.
+ */
+export function highlightTerms(query) {
+    return dedupe(tokenize(query)).sort((left, right) => right.length - left.length);
+}
+/**
+ * Remove duplicate tokens while preserving first-seen order.
+ * @param tokens - tokens to dedupe.
+ * @returns distinct tokens.
+ */
+function dedupe(tokens) {
+    return [...new Set(tokens)];
+}
+/**
+ * Whether a character is a CJK ideograph.
+ * @param char - one character.
+ * @returns true for an ideograph.
+ */
+export function isCjk(char) {
+    return CJK.test(char);
+}
+//# sourceMappingURL=tokenize.js.map

package/lib/types.d.ts

@@ -0,0 +1,353 @@
+/**
+ * The normalized vocabulary of the session-graph seam: what a caller may ask, what a store must
+ * answer, and what an indexer must report.
+ *
+ * Everything here is provider-neutral. A store ranges over one SQLite file today, but nothing in
+ * these types says so: `indexRoot` is an opaque directory the store claims, and a future store could
+ * serve it from anywhere. The seam therefore never exposes SQL, never exposes a schema version, and
+ * never exposes a path to a table — only sessions, entries, and search hits.
+ * @module dsh-plugin-sessiongraph-service/types
+ */
+import type { SessiongraphIndexerId, SessiongraphSessionId, SessiongraphStoreId } from './brand.ts';
+/** Every query operation the seam answers. */
+export declare const SESSIONGRAPH_OPERATIONS: readonly ["search", "session", "timeline", "workspaces", "status"];
+/** One query operation. */
+export type SessiongraphOperation = (typeof SESSIONGRAPH_OPERATIONS)[number];
+/**
+ * What a searchable entry is, from the reader's point of view.
+ *
+ * `user` is text a human actually typed; `assistant` is the model's visible reply (never its
+ * reasoning); `tool` is a tool invocation (its name and arguments, never the result body); `title`
+ * is a session title, kept as its own kind so a title match is recognizable in the hit list.
+ */
+export declare const SESSIONGRAPH_ENTRY_KINDS: readonly ["user", "assistant", "tool", "title"];
+/** One entry kind. */
+export type SessiongraphEntryKind = (typeof SESSIONGRAPH_ENTRY_KINDS)[number];
+/** Error codes the seam raises, so a consumer can distinguish "no index" from "bad request". */
+export type SessiongraphErrorCode = 'SESSIONGRAPH_UNAVAILABLE' | 'SESSIONGRAPH_CONFLICT' | 'SESSIONGRAPH_INVALID_PROVIDER' | 'SESSIONGRAPH_INVALID_REQUEST' | 'SESSIONGRAPH_NOT_FOUND' | 'SESSIONGRAPH_CORRUPT' | 'SESSIONGRAPH_IO';
+/** The single error type crossing the seam. */
+export declare class SessiongraphError extends Error {
+    readonly code: SessiongraphErrorCode;
+    /**
+     * @param message - human-readable diagnosis.
+     * @param code - machine-readable category.
+     */
+    constructor(message: string, code: SessiongraphErrorCode);
+}
+/** Fields every query request carries. */
+export interface SessiongraphRequestBase {
+    /** Directory holding the index this request targets. The seam routes on it; a store claims it. */
+    indexRoot: string;
+}
+/** Full-text search across indexed conversation history. */
+export interface SessiongraphSearchRequest extends SessiongraphRequestBase {
+    operation: 'search';
+    /** Query text. Chinese is matched by character bigram, so a two-character term works. */
+    query: string;
+    /** Restrict to one workspace (exact `cwd`), or a path prefix when it ends without a trailing slash. */
+    workspace?: string;
+    /** Only entries at or after this epoch-millisecond timestamp. */
+    after?: number;
+    /** Only entries at or before this epoch-millisecond timestamp. */
+    before?: number;
+    /** Restrict to these entry kinds. Absent means every kind. */
+    kinds?: readonly SessiongraphEntryKind[];
+    /** Maximum hits to return. */
+    limit: number;
+    /** Hits to skip, for paging. */
+    offset?: number;
+}
+/** One matched entry, with enough context to recognize it without a second query. */
+export interface SessiongraphHit {
+    sessionId: SessiongraphSessionId;
+    /** Session title, when the session ever produced one. */
+    title: string | undefined;
+    /** The session's working directory. */
+    workspace: string;
+    /** Entry timestamp, epoch milliseconds. */
+    time: number;
+    /** What matched. */
+    kind: SessiongraphEntryKind;
+    /** Event sequence number inside the session. */
+    seq: number;
+    /** Turn number inside the session, when the entry belongs to a turn. */
+    turn: number | undefined;
+    /** Matched text with the matched span wrapped in `[` `]`, truncated around the first match. */
+    snippet: string;
+    /** Total characters in the indexed entry, so a caller can tell a clip from the whole. */
+    length: number;
+}
+/** Answer to a search request. */
+export interface SessiongraphSearchResult {
+    operation: 'search';
+    hits: SessiongraphHit[];
+    /** Total entries matching the query across the whole store, before `limit`/`offset`. */
+    total: number;
+    /** True when `total` exceeded `limit + offset`, or when a snippet was clipped. */
+    truncated: boolean;
+}
+/** A session's metadata, as the timeline and session operations report it. */
+export interface SessiongraphSessionSummary {
+    sessionId: SessiongraphSessionId;
+    title: string | undefined;
+    workspace: string;
+    /** Epoch milliseconds of the session's first event. */
+    createdAt: number;
+    /** Epoch milliseconds of the session's last event. */
+    lastAt: number;
+    /** Number of turns the session contains. */
+    turns: number;
+    /** Number of indexed entries the session contributes. */
+    entries: number;
+    /** Parent session id, when this session was delegated from another. */
+    parentSession: string | undefined;
+    /** Session origin label (`user`, `subagent`, …), when the log records one. */
+    origin: string | undefined;
+    /** Agent preset the session ran under, when recorded. */
+    agentPreset: string | undefined;
+}
+/** One indexed entry, as the session operation reports it. */
+export interface SessiongraphEntry {
+    seq: number;
+    time: number;
+    kind: SessiongraphEntryKind;
+    turn: number | undefined;
+    /** Entry text, already bounded by the indexer's per-entry cap. */
+    text: string;
+    /** True when the indexer stored a clipped prefix instead of the whole entry. */
+    clipped: boolean;
+}
+/** Read one session, by full id or by an unambiguous prefix. */
+export interface SessiongraphSessionRequest extends SessiongraphRequestBase {
+    operation: 'session';
+    /** Full session id, or a prefix long enough to identify exactly one session. */
+    sessionId: string;
+    /** Maximum entries to return. */
+    limit: number;
+    /** Entries to skip, for paging; follows the session's own chronological order. */
+    offset?: number;
+}
+/** Answer to a session request. */
+export interface SessiongraphSessionResult {
+    operation: 'session';
+    session: SessiongraphSessionSummary;
+    entries: SessiongraphEntry[];
+    /** Sessions delegated from this one, oldest first. */
+    children: SessiongraphSessionId[];
+    /** True when the session holds more entries than `limit + offset`. */
+    truncated: boolean;
+}
+/** List sessions by time. */
+export interface SessiongraphTimelineRequest extends SessiongraphRequestBase {
+    operation: 'timeline';
+    /** Restrict to one workspace, or a path prefix when it ends without a trailing slash. */
+    workspace?: string;
+    /** Only sessions whose last event is at or after this epoch-millisecond timestamp. */
+    after?: number;
+    /** Only sessions whose first event is at or before this epoch-millisecond timestamp. */
+    before?: number;
+    /** Maximum sessions to return, newest first. */
+    limit: number;
+}
+/** Answer to a timeline request. */
+export interface SessiongraphTimelineResult {
+    operation: 'timeline';
+    sessions: SessiongraphSessionSummary[];
+    /** True when more sessions match than were returned. */
+    truncated: boolean;
+}
+/** Enumerate the workspaces the index covers. */
+export interface SessiongraphWorkspacesRequest extends SessiongraphRequestBase {
+    operation: 'workspaces';
+    /** Maximum workspaces to return, most recently active first. */
+    limit: number;
+}
+/** One workspace's coverage. */
+export interface SessiongraphWorkspaceStat {
+    workspace: string;
+    sessions: number;
+    entries: number;
+    /** Epoch milliseconds of the oldest session in this workspace. */
+    firstAt: number;
+    /** Epoch milliseconds of the newest session in this workspace. */
+    lastAt: number;
+}
+/** Answer to a workspaces request. */
+export interface SessiongraphWorkspacesResult {
+    operation: 'workspaces';
+    workspaces: SessiongraphWorkspaceStat[];
+    /** Total workspaces in the index, before `limit`. */
+    total: number;
+}
+/** Report the index's own state. Unlike every other operation, this one answers even when no index exists. */
+export interface SessiongraphStatusRequest extends SessiongraphRequestBase {
+    operation: 'status';
+}
+/** Answer to a status request. */
+export interface SessiongraphStatusResult {
+    operation: 'status';
+    /** False when `indexRoot` holds no index at all; every other field is then zero/empty. */
+    indexed: boolean;
+    /** Absolute path of the index file, for a caller that wants to inspect it directly. */
+    indexPath: string;
+    /** Sessions in the index. */
+    sessions: number;
+    /**
+     * Sessions whose source is the synthetic `live://<session-id>` marker rather than a log file:
+     * conversations that are still running and have not been written to disk yet. The count drops back
+     * to zero once each one ends and is re-indexed from its log. A store that cannot distinguish live
+     * sources omits the field; one that can always reports a number, `0` when every session is on disk.
+     */
+    liveSessions?: number;
+    /** Searchable entries in the index. */
+    entries: number;
+    /** Distinct workspaces in the index. */
+    workspaces: number;
+    /** Epoch milliseconds of the last successful index run, or undefined when never run. */
+    indexedAt: number | undefined;
+    /** Bytes the index file occupies on disk. */
+    bytes: number;
+}
+/** Every request the seam accepts, discriminated on `operation`. */
+export type SessiongraphRequest = SessiongraphSearchRequest | SessiongraphSessionRequest | SessiongraphTimelineRequest | SessiongraphWorkspacesRequest | SessiongraphStatusRequest;
+/** The result type a given request produces. */
+export type SessiongraphResultFor<R extends SessiongraphRequest> = R extends SessiongraphSearchRequest ? SessiongraphSearchResult : R extends SessiongraphSessionRequest ? SessiongraphSessionResult : R extends SessiongraphTimelineRequest ? SessiongraphTimelineResult : R extends SessiongraphWorkspacesRequest ? SessiongraphWorkspacesResult : R extends SessiongraphStatusRequest ? SessiongraphStatusResult : never;
+/** Every result the seam produces. */
+export type SessiongraphResult = SessiongraphSearchResult | SessiongraphSessionResult | SessiongraphTimelineResult | SessiongraphWorkspacesResult | SessiongraphStatusResult;
+/**
+ * A read provider: answers queries from an index it claims.
+ *
+ * `indexes` is asked for every registered store on every query, so it must be cheap (a stat, not a
+ * full open). Returning `false` is how a store declines a root it does not serve; a store never
+ * silently answers for a root it did not claim.
+ */
+export interface SessiongraphStoreProvider {
+    /** Stable identity, unique among registered stores. */
+    readonly id: SessiongraphStoreId;
+    /**
+     * Whether this store can answer for `indexRoot`.
+     * @param indexRoot - directory the caller targeted.
+     * @param signal - aborts the check.
+     */
+    indexes(indexRoot: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Answer one query. The request's `operation` selects the shape; a store must answer every
+     * operation it can, and raise {@link SessiongraphError} rather than guess.
+     * @param request - the normalized request.
+     * @param signal - aborts the query.
+     */
+    query<R extends SessiongraphRequest>(request: R, signal?: AbortSignal): Promise<SessiongraphResultFor<R>>;
+}
+/** Options an indexer accepts for one run. */
+export interface SessiongraphIndexOptions {
+    /**
+     * Rebuild every session from scratch. Without it a run skips sessions whose source file is
+     * unchanged since the last run.
+     */
+    force?: boolean;
+    /** Index only sessions whose `cwd` matches this workspace (exact, or a prefix without a trailing slash). */
+    workspace?: string;
+    /** Index only one session, by full id or unambiguous prefix. */
+    sessionId?: string;
+}
+/** What one index run did. */
+export interface SessiongraphIndexReport {
+    /** Absolute path of the index the run wrote. */
+    indexPath: string;
+    /** Sessions added since the previous run. */
+    added: number;
+    /** Sessions whose source changed and were re-written. */
+    updated: number;
+    /** Sessions skipped because their source was unchanged. */
+    skipped: number;
+    /** Sessions dropped because their source file disappeared. */
+    removed: number;
+    /**
+     * Sessions rebuilt from the host's live (still-running) view this run. They belong to no source
+     * file yet, are replayed in full on every run rather than compared by version, and are therefore
+     * not counted in `added`/`updated`/`skipped`.
+     */
+    liveSessions?: number;
+    /** Live sessions left out because they exceeded the indexer's configured cap. */
+    liveSkipped?: number;
+    /**
+     * Engine that produced this run's totals: the native Rust kernel or the TypeScript indexer. Absent
+     * on reports from a build that predates engine selection.
+     */
+    engine?: 'native' | 'typescript';
+    /** Sessions discovered in total across all source roots. */
+    discovered: number;
+    /** Sessions that failed to parse, with a bounded reason. */
+    failed: {
+        path: string;
+        reason: string;
+    }[];
+    /** Searchable entries written. */
+    entries: number;
+    /** Sessions in the index after the run. */
+    sessions: number;
+    /** Distinct workspaces in the index after the run. */
+    workspaces: number;
+    /** Bytes the index occupies after the run. */
+    bytes: number;
+    /** Wall-clock duration of the run, milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * A write provider: parses session logs and builds the index a store reads.
+ *
+ * Indexing is never triggered from {@link SessiongraphService.query}. It is a caller-initiated,
+ * potentially slow operation on its own timeout budget.
+ */
+export interface SessiongraphIndexer {
+    /** Stable identity, unique among registered indexers. */
+    readonly id: SessiongraphIndexerId;
+    /**
+     * Whether this indexer can build an index under `indexRoot`.
+     * @param indexRoot - directory the caller targeted.
+     * @param signal - aborts the check.
+     */
+    canIndex(indexRoot: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Build or refresh the index.
+     * @param indexRoot - directory to write into.
+     * @param options - scope and rebuild switches.
+     * @param signal - aborts the run; a store must leave the previous index readable.
+     */
+    index(indexRoot: string, options: SessiongraphIndexOptions, signal?: AbortSignal): Promise<SessiongraphIndexReport>;
+}
+/** The facade `ctx.sessiongraph` publishes. */
+export interface SessiongraphService {
+    /**
+     * Register a read provider.
+     * @param provider - the store to publish.
+     * @returns a disposer that unregisters it.
+     */
+    registerStore(provider: SessiongraphStoreProvider): () => void;
+    /**
+     * Register a write provider.
+     * @param provider - the indexer to publish.
+     * @returns a disposer that unregisters it.
+     */
+    registerIndexer(provider: SessiongraphIndexer): () => void;
+    /**
+     * Whether any store can answer for `indexRoot`.
+     * @param indexRoot - directory to test.
+     * @param signal - aborts the check.
+     */
+    available(indexRoot: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Answer one query through the single store claiming the request's `indexRoot`.
+     * @param request - the normalized request.
+     * @param signal - aborts the query.
+     */
+    query<R extends SessiongraphRequest>(request: R, signal?: AbortSignal): Promise<SessiongraphResultFor<R>>;
+    /**
+     * Run the single indexer claiming `indexRoot`.
+     * @param indexRoot - directory to build into.
+     * @param options - scope and rebuild switches.
+     * @param signal - aborts the run.
+     */
+    index(indexRoot: string, options?: SessiongraphIndexOptions, signal?: AbortSignal): Promise<SessiongraphIndexReport>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,34 @@
+/**
+ * The normalized vocabulary of the session-graph seam: what a caller may ask, what a store must
+ * answer, and what an indexer must report.
+ *
+ * Everything here is provider-neutral. A store ranges over one SQLite file today, but nothing in
+ * these types says so: `indexRoot` is an opaque directory the store claims, and a future store could
+ * serve it from anywhere. The seam therefore never exposes SQL, never exposes a schema version, and
+ * never exposes a path to a table — only sessions, entries, and search hits.
+ * @module dsh-plugin-sessiongraph-service/types
+ */
+/** Every query operation the seam answers. */
+export const SESSIONGRAPH_OPERATIONS = ['search', 'session', 'timeline', 'workspaces', 'status'];
+/**
+ * What a searchable entry is, from the reader's point of view.
+ *
+ * `user` is text a human actually typed; `assistant` is the model's visible reply (never its
+ * reasoning); `tool` is a tool invocation (its name and arguments, never the result body); `title`
+ * is a session title, kept as its own kind so a title match is recognizable in the hit list.
+ */
+export const SESSIONGRAPH_ENTRY_KINDS = ['user', 'assistant', 'tool', 'title'];
+/** The single error type crossing the seam. */
+export class SessiongraphError extends Error {
+    code;
+    /**
+     * @param message - human-readable diagnosis.
+     * @param code - machine-readable category.
+     */
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SessiongraphError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "dsh-plugin-sessiongraph-service",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Service definition for the DeepSeek Harness session-graph seam (ctx.sessiongraph) — a store-provider and indexer-provider registry over local conversation history, plus the normalized query vocabulary the model-facing tool speaks",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "session",
+    "session-history",
+    "search",
+    "fts",
+    "conversation",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "CC ZHAO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CC19990113/dsh-plugin-sessiongraph.git",
+    "directory": "packages/service"
+  },
+  "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"
+  },
+  "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.