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

package/lib/normalize.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The small normalizations the writer and the resolver share: comment hygiene, identifier folding,
+ * declared-type classification, and a bounded edit distance for the resolver's last-tier match.
+ *
+ * Tokenization is deliberately *not* here — the one tokenizer lives in
+ * `dsh-plugin-dbgraph-service` (`tokenizeForSearch`) because the native writer reimplements it in
+ * Rust and the two must agree token for token.
+ * @module dsh-plugin-dbgraph-store/normalize
+ */
+/** The coarse type families the index stores in `columns.type_class`. */
+export type TypeClass = 'integer' | 'decimal' | 'string' | 'text' | 'bool' | 'datetime' | 'json' | 'binary' | 'unknown';
+/** Longest comment the index keeps. A comment is a hint, not a document. */
+export declare const MAX_COMMENT_LENGTH = 2000;
+/**
+ * Normalize a declared type onto a {@link TypeClass}. Order matters: `tinyint(1)` is MySQL's boolean
+ * spelling and is classified before the integer rule sees it.
+ * @param type - the declared type, verbatim from the server.
+ * @returns the coarse family; `unknown` for an empty or unrecognized declaration.
+ */
+export declare function typeClassOf(type: string): TypeClass;
+/**
+ * Clean a comment for storage and indexing: NFKC, control characters collapsed to spaces, runs of
+ * whitespace folded, trimmed, and capped at {@link MAX_COMMENT_LENGTH}.
+ * @param comment - the comment the server reported, if any.
+ * @returns the cleaned comment, or undefined when nothing usable remains.
+ */
+export declare function normalizeComment(comment: string | undefined): string | undefined;
+/**
+ * Fold an identifier for exact and fuzzy comparison: NFKC, lower-case, and every separator removed, so
+ * `user_id`, `userId` and `USER-ID` all become `userid`.
+ * @param name - the identifier (or a user's word).
+ * @returns the folded form; empty when the input holds no letter or digit.
+ */
+export declare function normalizeIdentifier(name: string): string;
+/**
+ * Whether a token the service tokenizer emitted is pure ASCII (an identifier part) rather than a CJK
+ * bigram. The writer weights the two differently, because a bigram is partial evidence by nature.
+ * @param token - one token from `tokenizeForSearch`.
+ * @returns true for `[a-z0-9]+`.
+ */
+export declare function isAsciiToken(token: string): boolean;
+/**
+ * Whether a string contains a CJK character.
+ * @param text - the text to inspect.
+ * @returns true when at least one CJK character is present.
+ */
+export declare function hasCjk(text: string): boolean;
+/**
+ * Levenshtein distance, abandoned as soon as it is known to exceed `max`.
+ *
+ * The resolver's fuzzy tier is bounded at two edits on short identifiers, so the full quadratic table
+ * is never needed; the early exit also keeps a long column name from costing anything.
+ * @param left - first string, already folded.
+ * @param right - second string, already folded.
+ * @param max - the largest distance worth reporting.
+ * @returns the distance when it is at most `max`, else `max + 1`.
+ */
+export declare function levenshteinWithin(left: string, right: string, max: number): number;
+//# sourceMappingURL=normalize.d.ts.map

package/lib/normalize.js

@@ -0,0 +1,158 @@
+/**
+ * The small normalizations the writer and the resolver share: comment hygiene, identifier folding,
+ * declared-type classification, and a bounded edit distance for the resolver's last-tier match.
+ *
+ * Tokenization is deliberately *not* here — the one tokenizer lives in
+ * `dsh-plugin-dbgraph-service` (`tokenizeForSearch`) because the native writer reimplements it in
+ * Rust and the two must agree token for token.
+ * @module dsh-plugin-dbgraph-store/normalize
+ */
+/** Longest comment the index keeps. A comment is a hint, not a document. */
+export const MAX_COMMENT_LENGTH = 2000;
+/** Longest identifier a fuzzy match will compare. */
+const MAX_FUZZY_LENGTH = 64;
+/** CJK ideographs and kana, the characters `normalizeIdentifier` keeps. */
+const CJK = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+/**
+ * Normalize a declared type onto a {@link TypeClass}. Order matters: `tinyint(1)` is MySQL's boolean
+ * spelling and is classified before the integer rule sees it.
+ * @param type - the declared type, verbatim from the server.
+ * @returns the coarse family; `unknown` for an empty or unrecognized declaration.
+ */
+export function typeClassOf(type) {
+    const normalized = type.normalize('NFKC').toLowerCase().trim();
+    if (normalized === '')
+        return 'unknown';
+    const base = normalized.replace(/\((?:[^)]*)\)/g, '').replace(/\bunsigned\b|\bzerofill\b/g, '').trim();
+    if (base === '')
+        return 'unknown';
+    if (/^tinyint\(1\)/.test(normalized) || /\bbool(ean)?\b/.test(base) || /^bit\b/.test(base))
+        return 'bool';
+    if (/^(big|small|medium|tiny)?int(eger)?\b/.test(base)
+        || /^(u?int(2|4|8)|int[0-9]|serial|bigserial|smallserial)\b/.test(base)
+        || /^rowid$/.test(base)
+        || /\binteger\b/.test(base)) {
+        return 'integer';
+    }
+    if (/^(decimal|numeric|number|dec|fixed|money|smallmoney)\b/.test(base)
+        || /^(float|double|real)\b/.test(base)
+        || /^float[48]\b/.test(base)
+        || /^double\b/.test(base)) {
+        return 'decimal';
+    }
+    if (/^(json|jsonb)\b/.test(base))
+        return 'json';
+    if (/^(timestamp|timestamptz|datetime|date|time|timetz|year|interval)\b/.test(base))
+        return 'datetime';
+    if (/^(blob|binary|varbinary|bytea|image|raw|bfile|long\s*blob|medium\s*blob|tiny\s*blob)\b/.test(base)) {
+        return 'binary';
+    }
+    if (/^(tiny|medium|long)?text\b|^ntext\b|^clob\b|^nclob\b/.test(base))
+        return 'text';
+    if (/^(n?char|character|varchar|nvarchar|varchar2|n?varchar2|enum|set|uuid|uniqueidentifier|citext)\b/.test(base)) {
+        return 'string';
+    }
+    if (/^(string|name|symbol)\b/.test(base))
+        return 'string';
+    if (/\bchar\b/.test(base) || /\bvarchar\b/.test(base))
+        return 'string';
+    return 'unknown';
+}
+/**
+ * Clean a comment for storage and indexing: NFKC, control characters collapsed to spaces, runs of
+ * whitespace folded, trimmed, and capped at {@link MAX_COMMENT_LENGTH}.
+ * @param comment - the comment the server reported, if any.
+ * @returns the cleaned comment, or undefined when nothing usable remains.
+ */
+export function normalizeComment(comment) {
+    if (comment === undefined)
+        return undefined;
+    const cleaned = comment
+        .normalize('NFKC')
+        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (cleaned === '')
+        return undefined;
+    return cleaned.length > MAX_COMMENT_LENGTH ? cleaned.slice(0, MAX_COMMENT_LENGTH) : cleaned;
+}
+/**
+ * Fold an identifier for exact and fuzzy comparison: NFKC, lower-case, and every separator removed, so
+ * `user_id`, `userId` and `USER-ID` all become `userid`.
+ * @param name - the identifier (or a user's word).
+ * @returns the folded form; empty when the input holds no letter or digit.
+ */
+export function normalizeIdentifier(name) {
+    return name
+        .normalize('NFKC')
+        .toLowerCase()
+        // Every Unicode letter and number survives, not just ASCII and CJK: folding a Cyrillic or
+        // accented identifier to '' would make it unmatchable, and `find` would then answer "no such
+        // column" about a column that exists. `\p{Alphabetic}\p{N}` is the set the Rust twin's
+        // `char::is_alphanumeric` reports, so the two writers keep folding to the same form.
+        .replace(/[^\p{Alphabetic}\p{N}]/gu, '');
+}
+/**
+ * Whether a token the service tokenizer emitted is pure ASCII (an identifier part) rather than a CJK
+ * bigram. The writer weights the two differently, because a bigram is partial evidence by nature.
+ * @param token - one token from `tokenizeForSearch`.
+ * @returns true for `[a-z0-9]+`.
+ */
+export function isAsciiToken(token) {
+    return /^[a-z0-9]+$/.test(token);
+}
+/**
+ * Whether a string contains a CJK character.
+ * @param text - the text to inspect.
+ * @returns true when at least one CJK character is present.
+ */
+export function hasCjk(text) {
+    return CJK.test(text);
+}
+/**
+ * Levenshtein distance, abandoned as soon as it is known to exceed `max`.
+ *
+ * The resolver's fuzzy tier is bounded at two edits on short identifiers, so the full quadratic table
+ * is never needed; the early exit also keeps a long column name from costing anything.
+ * @param left - first string, already folded.
+ * @param right - second string, already folded.
+ * @param max - the largest distance worth reporting.
+ * @returns the distance when it is at most `max`, else `max + 1`.
+ */
+export function levenshteinWithin(left, right, max) {
+    const a = left.length > MAX_FUZZY_LENGTH ? left.slice(0, MAX_FUZZY_LENGTH) : left;
+    const b = right.length > MAX_FUZZY_LENGTH ? right.slice(0, MAX_FUZZY_LENGTH) : right;
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    if (a === '')
+        return b.length <= max ? b.length : max + 1;
+    if (b === '')
+        return a.length <= max ? a.length : max + 1;
+    let previous = new Array(b.length + 1);
+    let current = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j += 1)
+        previous[j] = j;
+    for (let i = 1; i <= a.length; i += 1) {
+        current[0] = i;
+        let rowBest = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            const deletion = previous[j] + 1;
+            const insertion = current[j - 1] + 1;
+            const value = Math.min(substitution, deletion, insertion);
+            current[j] = value;
+            if (value < rowBest)
+                rowBest = value;
+        }
+        if (rowBest > max)
+            return max + 1;
+        const swap = previous;
+        previous = current;
+        current = swap;
+    }
+    const distance = previous[b.length];
+    return distance <= max ? distance : max + 1;
+}
+//# sourceMappingURL=normalize.js.map

package/lib/paths.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Where dbgraph keeps its files, and the one switch that relocates them.
+ *
+ * Everything lives under a single root (`~/.dsh/dbgraph` by default):
+ *
+ * - `<root>/connections.json` — the connection list,
+ * - `<root>/<connection>/index.db` — one SQLite index per connection,
+ * - `<root>/status.json` — the prompt digest read synchronously on every prompt assembly.
+ *
+ * `DSH_DBGRAPH_ROOT` overrides the root so a test (or a deployment that keeps profile state somewhere
+ * else) never touches the real harness home. A store instance resolves the root once at construction;
+ * the free functions take an explicit root and fall back to the environment so a lone caller (a
+ * config surface, a test of `connections.json`) does not need a store first.
+ * @module dsh-plugin-dbgraph-store/paths
+ */
+/** Environment variable that relocates the whole index root. */
+export declare const ROOT_ENV = "DSH_DBGRAPH_ROOT";
+/**
+ * How long a staging file may sit before a write treats it as abandoned.
+ *
+ * A run that dies between creating its staging file and renaming it leaves that file behind forever
+ * (the path is per-run, so no later run reuses or removes it). One hour is far past any real build —
+ * the measured worst case on a 10k-column catalog is seconds — and short enough that a directory does
+ * not accumulate junk indefinitely.
+ */
+export declare const STALE_STAGING_MAX_AGE_MS: number;
+/**
+ * The index root: `DSH_DBGRAPH_ROOT` when set and non-empty, else `~/.dsh/dbgraph`.
+ * @returns an absolute directory path (an override may be relative; callers treat it as-is).
+ */
+export declare function indexRoot(): string;
+/**
+ * One connection's private directory.
+ * @param id - connection identity (already validated by the caller).
+ * @param root - index root; defaults to {@link indexRoot}.
+ * @returns the directory path, whether or not it exists.
+ */
+export declare function connectionDir(id: string, root?: string): string;
+/**
+ * One connection's index file.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns the path, whether or not the file exists.
+ */
+export declare function indexPath(id: string, root?: string): string;
+/**
+ * A staging path unique to one write.
+ *
+ * A plain `<index>.tmp` is not enough: two index runs for the same connection would share it, and one
+ * run could delete or rename the other's half-written file. The nonce is per call, so a run only ever
+ * cleans up and renames a file it created itself.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns `<index>.<pid>-<nonce>.tmp`, on the same filesystem so the rename is atomic.
+ */
+export declare function stagingIndexPath(id: string, root?: string): string;
+/**
+ * Remove staging files a previous run abandoned beside one index.
+ *
+ * The per-run nonce fixes the original collision (two runs cannot share a staging file) but turns
+ * each leak into a permanent one: a run killed between `open` and `rename` leaves
+ * `<index>.<pid>-<nonce>.tmp` behind and no later run would ever reuse that name. Only files older
+ * than {@link STALE_STAGING_MAX_AGE_MS} are removed, so a run that is merely slow — or a second run
+ * holding its own fresh staging file — is never touched. Removal failures are ignored: the file is
+ * junk, and a concurrent writer may remove it first.
+ * @param indexFile - the connection's live index path (the staging files share its directory).
+ * @param now - clock override, for tests.
+ * @returns the paths that were removed.
+ */
+export declare function sweepStaleStaging(indexFile: string, now?: number): string[];
+/**
+ * The connection list.
+ * @param root - index root.
+ * @returns `<root>/connections.json`.
+ */
+export declare function connectionsPath(root?: string): string;
+/**
+ * The prompt digest sidecar.
+ * @param root - index root.
+ * @returns `<root>/status.json`.
+ */
+export declare function statusPath(root?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/lib/paths.js

@@ -0,0 +1,130 @@
+/**
+ * Where dbgraph keeps its files, and the one switch that relocates them.
+ *
+ * Everything lives under a single root (`~/.dsh/dbgraph` by default):
+ *
+ * - `<root>/connections.json` — the connection list,
+ * - `<root>/<connection>/index.db` — one SQLite index per connection,
+ * - `<root>/status.json` — the prompt digest read synchronously on every prompt assembly.
+ *
+ * `DSH_DBGRAPH_ROOT` overrides the root so a test (or a deployment that keeps profile state somewhere
+ * else) never touches the real harness home. A store instance resolves the root once at construction;
+ * the free functions take an explicit root and fall back to the environment so a lone caller (a
+ * config surface, a test of `connections.json`) does not need a store first.
+ * @module dsh-plugin-dbgraph-store/paths
+ */
+import { randomUUID } from 'node:crypto';
+import { readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { CONNECTIONS_FILE_NAME, INDEX_FILE_NAME, INDEX_ROOT_DIRNAME, STATUS_FILE_NAME, } from 'dsh-plugin-dbgraph-service';
+/** Environment variable that relocates the whole index root. */
+export const ROOT_ENV = 'DSH_DBGRAPH_ROOT';
+/**
+ * How long a staging file may sit before a write treats it as abandoned.
+ *
+ * A run that dies between creating its staging file and renaming it leaves that file behind forever
+ * (the path is per-run, so no later run reuses or removes it). One hour is far past any real build —
+ * the measured worst case on a 10k-column catalog is seconds — and short enough that a directory does
+ * not accumulate junk indefinitely.
+ */
+export const STALE_STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+/**
+ * The index root: `DSH_DBGRAPH_ROOT` when set and non-empty, else `~/.dsh/dbgraph`.
+ * @returns an absolute directory path (an override may be relative; callers treat it as-is).
+ */
+export function indexRoot() {
+    const override = process.env[ROOT_ENV]?.trim();
+    if (override !== undefined && override !== '')
+        return override;
+    return join(homedir(), '.dsh', INDEX_ROOT_DIRNAME);
+}
+/**
+ * One connection's private directory.
+ * @param id - connection identity (already validated by the caller).
+ * @param root - index root; defaults to {@link indexRoot}.
+ * @returns the directory path, whether or not it exists.
+ */
+export function connectionDir(id, root = indexRoot()) {
+    return join(root, id);
+}
+/**
+ * One connection's index file.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns the path, whether or not the file exists.
+ */
+export function indexPath(id, root = indexRoot()) {
+    return join(connectionDir(id, root), INDEX_FILE_NAME);
+}
+/**
+ * A staging path unique to one write.
+ *
+ * A plain `<index>.tmp` is not enough: two index runs for the same connection would share it, and one
+ * run could delete or rename the other's half-written file. The nonce is per call, so a run only ever
+ * cleans up and renames a file it created itself.
+ * @param id - connection identity.
+ * @param root - index root.
+ * @returns `<index>.<pid>-<nonce>.tmp`, on the same filesystem so the rename is atomic.
+ */
+export function stagingIndexPath(id, root = indexRoot()) {
+    return `${indexPath(id, root)}.${process.pid}-${randomUUID().slice(0, 8)}.tmp`;
+}
+/**
+ * Remove staging files a previous run abandoned beside one index.
+ *
+ * The per-run nonce fixes the original collision (two runs cannot share a staging file) but turns
+ * each leak into a permanent one: a run killed between `open` and `rename` leaves
+ * `<index>.<pid>-<nonce>.tmp` behind and no later run would ever reuse that name. Only files older
+ * than {@link STALE_STAGING_MAX_AGE_MS} are removed, so a run that is merely slow — or a second run
+ * holding its own fresh staging file — is never touched. Removal failures are ignored: the file is
+ * junk, and a concurrent writer may remove it first.
+ * @param indexFile - the connection's live index path (the staging files share its directory).
+ * @param now - clock override, for tests.
+ * @returns the paths that were removed.
+ */
+export function sweepStaleStaging(indexFile, now = Date.now()) {
+    const directory = dirname(indexFile);
+    const prefix = `${basename(indexFile)}.`;
+    let names;
+    try {
+        names = readdirSync(directory);
+    }
+    catch {
+        // No directory yet: the write that called this is about to create it.
+        return [];
+    }
+    const removed = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !name.endsWith('.tmp'))
+            continue;
+        const candidate = join(directory, name);
+        try {
+            if (now - statSync(candidate).mtimeMs <= STALE_STAGING_MAX_AGE_MS)
+                continue;
+            rmSync(candidate, { force: true });
+            removed.push(candidate);
+        }
+        catch {
+            // The file vanished, or its directory is not readable; either way there is nothing to clean.
+        }
+    }
+    return removed;
+}
+/**
+ * The connection list.
+ * @param root - index root.
+ * @returns `<root>/connections.json`.
+ */
+export function connectionsPath(root = indexRoot()) {
+    return join(root, CONNECTIONS_FILE_NAME);
+}
+/**
+ * The prompt digest sidecar.
+ * @param root - index root.
+ * @returns `<root>/status.json`.
+ */
+export function statusPath(root = indexRoot()) {
+    return join(root, STATUS_FILE_NAME);
+}
+//# sourceMappingURL=paths.js.map

package/lib/reader.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The read path over one connection's index: `state`, `schema`, `objects`, `columns`, `impact`, `refs`,
+ * plus the summary `record()` rebuilds the prompt digest from.
+ *
+ * Every operation here is offline and read-only by construction, and one rule separates them:
+ * {@link IndexReader.state} **never throws** — a configuration surface asking "is this indexed" must
+ * get an answer even when the file is missing or unusable — while every other read fails loudly, so
+ * "no index" and "empty index" never look the same.
+ *
+ * Identifiers that reach SQL as identifiers (as opposed to bound values) are never taken from the
+ * index's own text; the only identifier interpolation is a placeholder list whose length comes from a
+ * count we control.
+ * @module dsh-plugin-dbgraph-store/reader
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ColumnsRequest, ColumnsResult, ImpactRequest, ImpactResult, IndexState, ObjectsRequest, ObjectsResult, RefsRequest, RefsResult, SchemaRequest, SchemaResult } from 'dsh-plugin-dbgraph-service';
+import type { OpenedIndex } from './database.ts';
+/** One row of `objects`, as every read operation wants it. */
+export interface ObjectRecord {
+    /** SQLite rowid of the object. */
+    readonly id: number;
+    /** Namespace, or `''` when the engine has none. */
+    readonly schema: string;
+    /** Declared name. */
+    readonly name: string;
+    /** Node category. */
+    readonly kind: string;
+    /** Comment, already normalized. */
+    readonly comment: string | undefined;
+}
+/** One row of `columns`, as the resolver and the column listing want it. */
+export interface ColumnRecord {
+    /** SQLite rowid of the column. */
+    readonly id: number;
+    /** Declared name. */
+    readonly name: string;
+    /** Declared type, verbatim. */
+    readonly type: string;
+    /** Whether the column admits NULL. */
+    readonly nullable: boolean;
+    /** Declared default, rendered as text. */
+    readonly defaultValue: string | undefined;
+    /** Comment, already normalized. */
+    readonly comment: string | undefined;
+    /** Whether the column participates in the primary key. */
+    readonly isPrimaryKey: boolean;
+    /** Whether a single-column unique constraint covers it. */
+    readonly isUnique: boolean;
+    /** One-based position within the object. */
+    readonly ordinal: number;
+    /** Sampled distinct literals, when the enrichment pass captured them. */
+    readonly enumValues: readonly string[] | undefined;
+}
+/** Bounds the reader imposes on one call. */
+export interface ReaderConfig {
+    /** Hours after which an L2 snapshot is reported stale. */
+    readonly staleHours: number;
+    /** Index files kept open at once. */
+    readonly maxOpenIndexes: number;
+    /** Objects one `schema` call may return. */
+    readonly maxSchemaObjects: number;
+    /** Columns one `columns` call may return. */
+    readonly maxColumns: number;
+    /** Objects one `objects` call returns when the request names no limit. */
+    readonly defaultObjectLimit: number;
+    /** Digest entries written into the prompt sidecar. */
+    readonly maxDigestObjects: number;
+    /** Foreign-key hops one `impact` walk follows. */
+    readonly impactDepth: number;
+    /** Edges one `impact` or `refs` call may return. */
+    readonly maxRelations: number;
+}
+/** Defaults for a store mounted without tuning. */
+export declare const DEFAULT_READER_CONFIG: ReaderConfig;
+/** What an object lookup found, so a caller can report ambiguity instead of guessing. */
+export interface ObjectLookup {
+    /** The unique match, when there is exactly one. */
+    readonly record?: ObjectRecord;
+    /** Every match, when there was more than one. */
+    readonly matches: readonly ObjectRecord[];
+    /** Near misses offered when nothing matched. */
+    readonly suggestions: readonly ObjectRecord[];
+}
+/**
+ * Render an object for a model-facing surface.
+ * @param record - the object row.
+ * @returns `schema.name` when a schema is present, else `name`.
+ */
+export declare function displayName(record: ObjectRecord): string;
+/**
+ * Object ids matched by the FTS index, best rank first.
+ *
+ * Both document kinds count: an object document carries the table's own name and comment, a column
+ * document carries one column's — and a question about a field is a question about the table holding
+ * it. `bm25()` is lower-is-better, so merging keeps the minimum rank.
+ * @param db - the open index.
+ * @param match - an FTS expression.
+ * @param limit - maximum ids to return.
+ * @returns object ids in rank order.
+ */
+export declare function ftsObjectIds(db: DatabaseSync, match: string, limit: number): number[];
+/**
+ * Suggest objects when an exact name missed.
+ * @param db - the open index.
+ * @param words - what the caller typed.
+ * @returns up to five near matches, best first.
+ */
+export declare function suggestObjects(db: DatabaseSync, words: readonly string[]): ObjectRecord[];
+/**
+ * Locate an object by its listed name — bare (`sys_user`) or schema-qualified (`public.sys_user`).
+ * @param db - the open index.
+ * @param name - the name the caller used.
+ * @returns the unique match, the ambiguous matches, or suggestions.
+ */
+export declare function lookupObject(db: DatabaseSync, name: string): ObjectLookup;
+/**
+ * Load one object's columns in declared order.
+ * @param db - the open index.
+ * @param objectId - the object id.
+ * @param limit - maximum rows (a caller passes `cap + 1` to detect truncation).
+ * @returns column records.
+ */
+export declare function loadColumns(db: DatabaseSync, objectId: number, limit: number): ColumnRecord[];
+/**
+ * Load a set of objects by id.
+ * @param db - the open index.
+ * @param ids - their ids.
+ * @returns records keyed by id.
+ */
+export declare function loadObjects(db: DatabaseSync, ids: readonly number[]): Map<number, ObjectRecord>;
+/** The `reader` half of the store: one pool, one root, no network. */
+export declare class IndexReader {
+    private readonly root;
+    private readonly config;
+    private readonly pool;
+    /**
+     * @param root - index root.
+     * @param config - the bounds this reader imposes.
+     */
+    constructor(root: string, config?: ReaderConfig);
+    /**
+     * Open one connection's index, validating the identity first so no caller-supplied id becomes a
+     * path fragment.
+     * @param connection - connection identity.
+     * @returns the open index.
+     */
+    open(connection: string): OpenedIndex;
+    /**
+     * State of one connection's index. Never throws: an unusable index is reported as empty and stale.
+     * @param connection - connection identity.
+     * @returns the state.
+     */
+    state(connection: string): IndexState;
+    /**
+     * Structural overview.
+     * @param request - which connection.
+     * @returns the overview.
+     */
+    schema(request: SchemaRequest): SchemaResult;
+    /**
+     * Ranked object listing.
+     * @param request - which connection and what to look for.
+     * @returns the listing.
+     */
+    objects(request: ObjectsRequest): ObjectsResult;
+    /**
+     * One object's columns.
+     * @param request - which object.
+     * @returns the listing.
+     */
+    columns(request: ColumnsRequest): ColumnsResult;
+    /**
+     * Objects a change to this one reaches: the transitive inbound reference closure, nearest first.
+     * @param request - the object to trace.
+     * @returns the reached objects.
+     */
+    impact(request: ImpactRequest): ImpactResult;
+    /**
+     * Objects directly referencing this one.
+     * @param request - the object to trace.
+     * @returns the referencing objects.
+     */
+    refs(request: RefsRequest): RefsResult;
+    /**
+     * Close every cached connection. Idempotent.
+     */
+    close(): void;
+    /**
+     * State derived from an already-open index, so `schema` does not stat the file twice.
+     * @param opened - the open index.
+     * @returns the state.
+     */
+    private stateOf;
+    /**
+     * Fraction of columns carrying a comment.
+     * @param opened - the open index.
+     * @returns 0..1, and 0 for an empty index (no evidence, not full coverage).
+     */
+    private commentCoverageOf;
+    /**
+     * Clamp a requested object limit into the configured bounds.
+     * @param requested - the caller's value, when one was set.
+     * @returns a limit of at least 1, at most 500.
+     */
+    private objectLimit;
+}
+//# sourceMappingURL=reader.d.ts.map