dsh-plugin-dbgraph-store 0.0.0-stage → 0.1.0

package/lib/rust-engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Loader for the optional native index kernel (`crates/dbgraph-indexer`).
+ *
+ * The addon is optional at every level, the same posture `dsh-plugin-codegraph` takes with its Rust
+ * extractor: a missing artifact, an unsupported platform, an unloadable binary, or an unusable answer
+ * all mean "the JavaScript writer runs instead, it says so once, and nothing else changes".
+ *
+ * One deliberate exception to that posture: the caller that *asked* for `writer: 'rust'` gets an error
+ * rather than a silent fallback. A parity check that quietly compared JS against JS would be worse
+ * than a failed one.
+ *
+ * Artifact naming follows the build script (`dbgraph-indexer.<platform>-<arch>.node`, produced by
+ * `crates/dbgraph-indexer/build-addon.sh`). `napi build` names some targets with a qualifier
+ * (`linux-x64-gnu`, `win32-x64-msvc`), so both spellings are probed. `DSH_DBGRAPH_RUST_ADDON` may
+ * point at an explicit artifact — a test hook, and an escape hatch for a deployment that ships the
+ * binary outside the checkout.
+ * @module dsh-plugin-dbgraph-store/rust-engine
+ */
+import type { AliasGroup, RawCatalog } from 'dsh-plugin-dbgraph-service';
+/** Environment variable that overrides the addon path. */
+export declare const ADDON_ENV = "DSH_DBGRAPH_RUST_ADDON";
+/** What the addon's `buildIndex` returns. */
+export interface RustBuildReport {
+    /** Objects written. */
+    readonly objects: number;
+    /** Columns written. */
+    readonly columns: number;
+    /** Edges written. */
+    readonly edges: number;
+    /** Search terms written. */
+    readonly terms: number;
+    /** Wall-clock duration of the native call, in milliseconds. */
+    readonly elapsedMs: number;
+}
+/** What the addon's `buildIndex` accepts. */
+export interface RustBuildInput {
+    /** Absolute path of the `.tmp` index file. The caller renames it into place. */
+    readonly dbPath: string;
+    /** `INDEX_SCHEMA_DDL`, executed verbatim. */
+    readonly schemaDdl: readonly string[];
+    /** `INDEX_SCHEMA_VERSION`. */
+    readonly schemaVersion: number;
+    /** Connection identity stored in `meta.connection`. */
+    readonly connection: string;
+    /** `JSON.stringify(catalog)` — text transport keeps the conversion off the event loop. */
+    readonly catalogJson: string;
+    /** `JSON.stringify(aliases)`. */
+    readonly aliasesJson: string;
+    /** Epoch milliseconds to stamp on every row, so the caller controls time. */
+    readonly now: number;
+}
+/** The narrow surface this module needs from the addon. */
+export interface RustIndexer {
+    /** Write one complete index to `input.dbPath`. */
+    buildIndex(input: RustBuildInput): Promise<unknown>;
+}
+/** The result of one load attempt. */
+export interface RustLoad {
+    /** The loaded kernel, when the artifact is usable. */
+    readonly engine?: RustIndexer;
+    /** Why it could not be loaded; empty on success. */
+    readonly reason: string;
+    /** Absolute artifact path that was loaded, when one was found. */
+    readonly path?: string;
+}
+/**
+ * Where this host's artifact should be, and whether it is there.
+ *
+ * A missing file is not cached: an addon built while the host is running starts working on the next
+ * call without a restart. A file that exists but throws while loading *is* cached — a corrupt binary
+ * does not repair itself mid-process.
+ * @returns the first existing candidate, or the reason none did.
+ */
+export declare function resolveAddonPath(): {
+    readonly path?: string;
+    readonly reason: string;
+};
+/**
+ * Load the native kernel, or explain why it is not available.
+ * @returns the loaded kernel and the reason string for diagnostics.
+ */
+export declare function loadRustIndexer(): RustLoad;
+/**
+ * Validate and normalize the addon's answer.
+ *
+ * An addon that resolves with nonsense is treated exactly like an addon that threw: no partial answer
+ * ever reaches the rename, so `index.db` keeps describing the previous run.
+ * @param value - the resolved value of `buildIndex`.
+ * @returns the report, or undefined when it is not a usable one.
+ */
+export declare function parseRustReport(value: unknown): RustBuildReport | undefined;
+/** One catalog, ready to cross the addon boundary as text. */
+export interface RustPayload {
+    /** The snapshot. */
+    readonly catalog: RawCatalog;
+    /** The alias table the writer expands. */
+    readonly aliases: readonly AliasGroup[];
+}
+/**
+ * Serialize one payload for the text transport.
+ * @param payload - the catalog and aliases.
+ * @returns the two JSON strings the addon expects.
+ */
+export declare function serializePayload(payload: RustPayload): {
+    catalogJson: string;
+    aliasesJson: string;
+};
+//# sourceMappingURL=rust-engine.d.ts.map

package/lib/rust-engine.js

@@ -0,0 +1,148 @@
+/**
+ * Loader for the optional native index kernel (`crates/dbgraph-indexer`).
+ *
+ * The addon is optional at every level, the same posture `dsh-plugin-codegraph` takes with its Rust
+ * extractor: a missing artifact, an unsupported platform, an unloadable binary, or an unusable answer
+ * all mean "the JavaScript writer runs instead, it says so once, and nothing else changes".
+ *
+ * One deliberate exception to that posture: the caller that *asked* for `writer: 'rust'` gets an error
+ * rather than a silent fallback. A parity check that quietly compared JS against JS would be worse
+ * than a failed one.
+ *
+ * Artifact naming follows the build script (`dbgraph-indexer.<platform>-<arch>.node`, produced by
+ * `crates/dbgraph-indexer/build-addon.sh`). `napi build` names some targets with a qualifier
+ * (`linux-x64-gnu`, `win32-x64-msvc`), so both spellings are probed. `DSH_DBGRAPH_RUST_ADDON` may
+ * point at an explicit artifact — a test hook, and an escape hatch for a deployment that ships the
+ * binary outside the checkout.
+ * @module dsh-plugin-dbgraph-store/rust-engine
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Environment variable that overrides the addon path. */
+export const ADDON_ENV = 'DSH_DBGRAPH_RUST_ADDON';
+const require = createRequire(import.meta.url);
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+/** `<repo>/crates/dbgraph-indexer/artifacts` — three levels up from `src/` or `lib/`. */
+const artifactsDirectory = join(moduleDirectory, '..', '..', '..', 'crates', 'dbgraph-indexer', 'artifacts');
+/** Every artifact suffix this host could plausibly use, most specific build first. */
+function artifactSuffixes() {
+    const base = `${process.platform}-${process.arch}`;
+    const suffixes = [base];
+    if (process.platform === 'linux')
+        suffixes.push(`${base}-gnu`, `${base}-musl`);
+    else if (process.platform === 'win32')
+        suffixes.push(`${base}-msvc`);
+    return suffixes;
+}
+/** One load attempt's outcome is reused for the process lifetime, keyed by path. */
+let cachedPath;
+let cachedLoad;
+/**
+ * Where this host's artifact should be, and whether it is there.
+ *
+ * A missing file is not cached: an addon built while the host is running starts working on the next
+ * call without a restart. A file that exists but throws while loading *is* cached — a corrupt binary
+ * does not repair itself mid-process.
+ * @returns the first existing candidate, or the reason none did.
+ */
+export function resolveAddonPath() {
+    const override = process.env[ADDON_ENV]?.trim();
+    if (override !== undefined && override !== '') {
+        if (!existsSync(override)) {
+            return { reason: `${ADDON_ENV} points at ${override}, which does not exist` };
+        }
+        return { path: override, reason: `loaded from ${ADDON_ENV}` };
+    }
+    const tried = artifactSuffixes().map(suffix => join(artifactsDirectory, `dbgraph-indexer.${suffix}.node`));
+    for (const candidate of tried) {
+        if (existsSync(candidate))
+            return { path: candidate, reason: `found at ${candidate}` };
+    }
+    return {
+        reason: `no native artifact for ${process.platform}-${process.arch}; looked for ${tried.join(', ')}`,
+    };
+}
+/**
+ * Load the native kernel, or explain why it is not available.
+ * @returns the loaded kernel and the reason string for diagnostics.
+ */
+export function loadRustIndexer() {
+    const resolution = resolveAddonPath();
+    if (resolution.path === undefined)
+        return { reason: resolution.reason };
+    if (cachedLoad !== undefined && cachedPath === resolution.path)
+        return cachedLoad;
+    const path = resolution.path;
+    try {
+        const loaded = require(path);
+        const buildIndex = typeof loaded === 'object' && loaded !== null
+            ? loaded.buildIndex
+            : undefined;
+        if (typeof buildIndex !== 'function') {
+            const failed = { reason: `the addon at ${path} exports no buildIndex function`, path };
+            cachedPath = path;
+            cachedLoad = failed;
+            return failed;
+        }
+        const engine = {
+            buildIndex: async (input) => buildIndex.call(loaded, input),
+        };
+        const ready = { engine, reason: `loaded ${path}`, path };
+        cachedPath = path;
+        cachedLoad = ready;
+        return ready;
+    }
+    catch (error) {
+        const failed = {
+            reason: `the addon at ${path} failed to load: ${error instanceof Error ? error.message : String(error)}`,
+            path,
+        };
+        cachedPath = path;
+        cachedLoad = failed;
+        return failed;
+    }
+}
+/**
+ * Validate and normalize the addon's answer.
+ *
+ * An addon that resolves with nonsense is treated exactly like an addon that threw: no partial answer
+ * ever reaches the rename, so `index.db` keeps describing the previous run.
+ * @param value - the resolved value of `buildIndex`.
+ * @returns the report, or undefined when it is not a usable one.
+ */
+export function parseRustReport(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    const counts = [];
+    for (const key of ['objects', 'columns', 'edges', 'terms']) {
+        const count = record[key];
+        if (typeof count !== 'number' || !Number.isInteger(count) || count < 0)
+            return undefined;
+        counts.push(count);
+    }
+    const elapsedMs = record.elapsedMs;
+    if (typeof elapsedMs !== 'number' || !Number.isFinite(elapsedMs) || elapsedMs < 0)
+        return undefined;
+    return {
+        objects: counts[0],
+        columns: counts[1],
+        edges: counts[2],
+        terms: counts[3],
+        elapsedMs,
+    };
+}
+/**
+ * Serialize one payload for the text transport.
+ * @param payload - the catalog and aliases.
+ * @returns the two JSON strings the addon expects.
+ */
+export function serializePayload(payload) {
+    return {
+        catalogJson: JSON.stringify(payload.catalog),
+        aliasesJson: JSON.stringify(payload.aliases),
+    };
+}
+//# sourceMappingURL=rust-engine.js.map

package/lib/status.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The prompt-digest sidecar (`status.json`): a small JSON document every connection's index state is
+ * mirrored into, so the system-prompt section can answer "what does this database look like" with one
+ * synchronous `readFileSync` instead of an SQLite open per prompt assembly.
+ *
+ * It is a *derived* copy. The index file stays authoritative; a missing or unreadable sidecar only
+ * degrades one sentence. The one ordering rule that matters is placement: the writer renames the index
+ * into place first and records the digest second, so a reader can never describe an index that is not
+ * there yet (it may describe an older one, which is why `l1IndexedAt` is carried per entry).
+ * @module dsh-plugin-dbgraph-store/status
+ */
+import type { IndexLevel, RawObject, StatusConnectionEntry, StatusFile } from 'dsh-plugin-dbgraph-service';
+/** Format version of `status.json`; a reader that sees another one falls back to the weaker sentence. */
+export declare const STATUS_FORMAT_VERSION = 1;
+/**
+ * Render one object's display name the way every other surface does.
+ * @param object - a raw catalog object.
+ * @returns `schema.name` when a schema is present, else `name`.
+ */
+export declare function objectDisplayName(object: RawObject): string;
+/** What {@link buildStatusEntry} needs from a writer's run. */
+export interface StatusEntryInput {
+    /** Database family. */
+    readonly engine: string;
+    /** Human label from `connections.json`, when one is configured. */
+    readonly label?: string;
+    /** Which level the snapshot covers. */
+    readonly level: IndexLevel;
+    /** Epoch milliseconds the snapshot was taken. */
+    readonly fetchedAt: number;
+    /** Objects written. */
+    readonly objects: readonly RawObject[];
+    /** Column rows written (equal to the sum of the objects' columns unless a dialect disagreed). */
+    readonly columnCount: number;
+    /** Digest cap; defaults to {@link DEFAULT_STATUS_DIGEST_OBJECTS}. */
+    readonly maxDigestObjects?: number;
+}
+/**
+ * Build the sidecar entry for a writer's run.
+ * @param input - the catalog-derived facts.
+ * @returns the entry to store under the connection id.
+ */
+export declare function buildStatusEntry(input: StatusEntryInput): StatusConnectionEntry;
+/**
+ * Read the sidecar.
+ *
+ * Never throws: prompt assembly runs this on every request, so a corrupt or half-written file means
+ * "no digest", not "the prompt fails to assemble".
+ * @param root - index root.
+ * @returns the document, or undefined when it is absent or unusable.
+ */
+export declare function readStatusFile(root: string): StatusFile | undefined;
+/**
+ * Record one connection's entry, preserving every other connection's entry.
+ *
+ * A document at another format version is replaced rather than merged: this build cannot promise it
+ * understands a future entry's shape, and a fresh document is honest about being partial.
+ * @param root - index root.
+ * @param connectionId - the connection whose entry changed.
+ * @param entry - the fresh entry.
+ * @param now - epoch milliseconds of the write; defaults to now.
+ */
+export declare function writeStatusEntry(root: string, connectionId: string, entry: StatusConnectionEntry, now?: number): void;
+//# sourceMappingURL=status.d.ts.map

package/lib/status.js

@@ -0,0 +1,141 @@
+/**
+ * The prompt-digest sidecar (`status.json`): a small JSON document every connection's index state is
+ * mirrored into, so the system-prompt section can answer "what does this database look like" with one
+ * synchronous `readFileSync` instead of an SQLite open per prompt assembly.
+ *
+ * It is a *derived* copy. The index file stays authoritative; a missing or unreadable sidecar only
+ * degrades one sentence. The one ordering rule that matters is placement: the writer renames the index
+ * into place first and records the digest second, so a reader can never describe an index that is not
+ * there yet (it may describe an older one, which is why `l1IndexedAt` is carried per entry).
+ * @module dsh-plugin-dbgraph-store/status
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DEFAULT_STATUS_DIGEST_OBJECTS } from 'dsh-plugin-dbgraph-service';
+import { normalizeComment } from "./normalize.js";
+import { statusPath } from "./paths.js";
+/** Format version of `status.json`; a reader that sees another one falls back to the weaker sentence. */
+export const STATUS_FORMAT_VERSION = 1;
+/**
+ * Render one object's display name the way every other surface does.
+ * @param object - a raw catalog object.
+ * @returns `schema.name` when a schema is present, else `name`.
+ */
+export function objectDisplayName(object) {
+    const schema = object.schema ?? '';
+    return schema === '' ? object.name : `${schema}.${object.name}`;
+}
+/**
+ * Rank and cap the digest: the widest objects first (a column count is the one size signal every
+ * engine reports), name as the stable tie-break.
+ * @param objects - the snapshot's objects.
+ * @param maxEntries - the cap.
+ * @returns the digest and how many objects were left out.
+ */
+function buildDigest(objects, maxEntries) {
+    const ranked = objects
+        .map(object => {
+        const comment = normalizeComment(object.comment);
+        return {
+            object: objectDisplayName(object),
+            ...(comment === undefined ? {} : { comment }),
+            columns: object.columns.length,
+        };
+    })
+        .sort((left, right) => right.columns - left.columns || (left.object < right.object ? -1 : left.object > right.object ? 1 : 0));
+    const digest = ranked.slice(0, maxEntries);
+    return { digest, omitted: ranked.length - digest.length };
+}
+/**
+ * Build the sidecar entry for a writer's run.
+ * @param input - the catalog-derived facts.
+ * @returns the entry to store under the connection id.
+ */
+export function buildStatusEntry(input) {
+    const { digest, omitted } = buildDigest(input.objects, input.maxDigestObjects ?? DEFAULT_STATUS_DIGEST_OBJECTS);
+    let commented = 0;
+    for (const object of input.objects) {
+        for (const column of object.columns) {
+            if (normalizeComment(column.comment) !== undefined)
+                commented += 1;
+        }
+    }
+    const total = input.columnCount;
+    return {
+        engine: input.engine,
+        ...(input.label === undefined ? {} : { label: input.label }),
+        l1IndexedAt: input.fetchedAt,
+        ...(input.level === 'l2' ? { l2IndexedAt: input.fetchedAt } : {}),
+        objects: input.objects.length,
+        columns: total,
+        commentCoverage: total === 0 ? 0 : commented / total,
+        digest,
+        digestOmitted: omitted,
+    };
+}
+/**
+ * Read the sidecar.
+ *
+ * Never throws: prompt assembly runs this on every request, so a corrupt or half-written file means
+ * "no digest", not "the prompt fails to assemble".
+ * @param root - index root.
+ * @returns the document, or undefined when it is absent or unusable.
+ */
+export function readStatusFile(root) {
+    let text;
+    try {
+        text = readFileSync(statusPath(root), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const candidate = parsed;
+    if (typeof candidate.version !== 'number')
+        return undefined;
+    if (typeof candidate.connections !== 'object' || candidate.connections === null)
+        return undefined;
+    return {
+        version: candidate.version,
+        updatedAt: typeof candidate.updatedAt === 'number' ? candidate.updatedAt : 0,
+        connections: candidate.connections,
+    };
+}
+/**
+ * Record one connection's entry, preserving every other connection's entry.
+ *
+ * A document at another format version is replaced rather than merged: this build cannot promise it
+ * understands a future entry's shape, and a fresh document is honest about being partial.
+ * @param root - index root.
+ * @param connectionId - the connection whose entry changed.
+ * @param entry - the fresh entry.
+ * @param now - epoch milliseconds of the write; defaults to now.
+ */
+export function writeStatusEntry(root, connectionId, entry, now = Date.now()) {
+    const existing = readStatusFile(root);
+    const connections = existing?.version === STATUS_FORMAT_VERSION
+        ? { ...existing.connections }
+        : {};
+    connections[connectionId] = entry;
+    const document = { version: STATUS_FORMAT_VERSION, updatedAt: now, connections };
+    const target = statusPath(root);
+    mkdirSync(dirname(target), { recursive: true });
+    const staging = `${target}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(document)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        renameSync(staging, target);
+    }
+    catch (error) {
+        rmSync(staging, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=status.js.map

package/lib/terms.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The semantic layer of the index: `terms` rows and the FTS `search` documents.
+ *
+ * Two lookups answer the same question from opposite directions:
+ *
+ * - `terms` is the resolver's table — one row per (word, object[, column]) with a weight that says how
+ *   strong the evidence is: a column's name token beats its comment, an alias expansion beats neither,
+ *   a Chinese bigram beats nothing at all, it is partial evidence by construction.
+ * - `search` is the FTS5 document — the tokenizer's output for an object's name and comment (one row)
+ *   and for each column's name and comment (one row per column), used for free-text listing and as a
+ *   recall net behind the resolver.
+ *
+ * Weights live in one exported table so the resolver's expectations and the writer's output cannot
+ * drift apart silently.
+ * @module dsh-plugin-dbgraph-store/terms
+ */
+import type { AliasGroup, RawCatalog } from 'dsh-plugin-dbgraph-service';
+/**
+ * Evidence weight per token source. A column-level row is finally weighed again by the resolver
+ * (a column hit is weaker evidence about the *table* than the table's own name), so these numbers are
+ * "how much does this word describe the name it was found in", not final confidence.
+ */
+export declare const TERM_WEIGHTS: {
+    /** A token of the object's own name. */
+    readonly objectNameAscii: 1;
+    /** A CJK bigram of the object's name — partial by nature. */
+    readonly objectNameCjk: 0.75;
+    /** An ASCII token of the object's comment. */
+    readonly objectCommentAscii: 0.75;
+    /** A CJK bigram of the object's comment. */
+    readonly objectCommentCjk: 0.5;
+    /** An alias-group expansion on an object's name or comment. */
+    readonly objectAlias: 0.6;
+    /** An ASCII token of the column's own name. */
+    readonly columnNameAscii: 0.9;
+    /** A CJK bigram of the column's name. */
+    readonly columnNameCjk: 0.75;
+    /** An ASCII token of the column's comment. */
+    readonly columnCommentAscii: 0.7;
+    /** A CJK bigram of the column's comment. */
+    readonly columnCommentCjk: 0.5;
+    /** An alias-group expansion on a column's name or comment. */
+    readonly columnAlias: 0.65;
+};
+/** Object ids assigned in catalog order, and per-object column ids assigned in a global sequence. */
+export interface CatalogIds {
+    /** One one-based SQLite rowid per object, in catalog order. */
+    readonly objects: readonly number[];
+    /** Per object (same order), the one-based ids of its columns. */
+    readonly columns: readonly (readonly number[])[];
+}
+/**
+ * Assign the ids the writer will use, so terms and rows cannot disagree about identity.
+ * @param catalog - the snapshot being written.
+ * @returns object ids by position and column ids by object/column position.
+ */
+export declare function assignCatalogIds(catalog: RawCatalog): CatalogIds;
+/** One row of the `terms` table. */
+export interface TermRow {
+    /** The token, as the service tokenizer emits it. */
+    readonly term: string;
+    /** Evidence strength 0..1; see {@link TERM_WEIGHTS}. */
+    readonly weight: number;
+    /** Object this term describes, when it describes one. */
+    readonly objectId: number | null;
+    /** Column this term describes, when it describes one. */
+    readonly columnId: number | null;
+}
+/** One row of the `search` table (FTS5). */
+export interface SearchRow {
+    /** Pre-tokenized document, space-joined. */
+    readonly text: string;
+    /** Object identity for an object document; null for a column document. */
+    readonly objectId: number | null;
+    /** Column identity for a column document; null for an object document. */
+    readonly columnId: number | null;
+}
+/** Everything the semantic layer produces for one write. */
+export interface TermBuild {
+    /** Deduplicated `terms` rows. */
+    readonly terms: readonly TermRow[];
+    /** One object document per object, one column document per column. */
+    readonly search: readonly SearchRow[];
+}
+/**
+ * Build every `terms` row and both `search` documents for one catalog.
+ * @param catalog - the snapshot being written.
+ * @param ids - ids from {@link assignCatalogIds}.
+ * @param aliases - the alias table handed in by the caller.
+ * @returns deduplicated term rows and search documents.
+ */
+export declare function buildTerms(catalog: RawCatalog, ids: CatalogIds, aliases: readonly AliasGroup[]): TermBuild;
+//# sourceMappingURL=terms.d.ts.map