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

package/lib/resolve.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Offline semantic resolution: user words in, one table plus one parameterized `WHERE` out.
+ *
+ * The resolver is deliberately conservative in one direction and generous in the other: it accepts a
+ * loose list of candidates (a wrong word in the alias table only costs one ranked alternative) but
+ * refuses to answer when more than one table fits, when the best fit is below the confidence gate, or
+ * when the request names no table, entity, or condition at all. The failure it must never produce is a
+ * confident `SELECT *` over the wrong table.
+ *
+ * Scoring, in one sentence: a candidate's score is `0.85 × best evidence + 0.15 × concept coverage`,
+ * where evidence is a term weight (a table's own name beats a comment, a column reached through an
+ * alias is weighed again at 0.8 because it is weaker evidence about the *table*), and concepts are the
+ * user's words after alias expansion. The two knobs a deployment may retune are the gate
+ * (`minConfidence`, default 0.6) and the tie margin (`ambiguityGap`, default 0.15).
+ * @module dsh-plugin-dbgraph-store/resolve
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { AliasGroup, FindRequest, Resolution } from 'dsh-plugin-dbgraph-service';
+/** How much a column hit counts as evidence about the table that owns it. */
+export declare const COLUMN_EVIDENCE_FACTOR = 0.8;
+/** Weight of the single best evidence token in the score. */
+export declare const BEST_WEIGHT_SHARE = 0.85;
+/** Weight of concept coverage in the score. */
+export declare const COVERAGE_SHARE = 0.15;
+/** When only the FTS index recalls an object, its score starts here. */
+export declare const FTS_FALLBACK_TOP = 0.62;
+/** Rank penalty per additional FTS-only candidate. */
+export declare const FTS_FALLBACK_STEP = 0.02;
+/** Lowest score an FTS-only candidate is given. */
+export declare const FTS_FALLBACK_FLOOR = 0.5;
+/** How the resolver is tuned. */
+export interface ResolveOptions {
+    /** Alias table expanded into the query and used by the synonym tier. */
+    readonly aliases: readonly AliasGroup[];
+    /** Below this, the answer is `ambiguous` rather than `resolved`. Default 0.6. */
+    readonly minConfidence: number;
+    /** A top-2 margin smaller than this is `ambiguous`. Default 0.15. */
+    readonly ambiguityGap: number;
+    /** Candidates returned when resolution was not decisive. Default 5. */
+    readonly maxCandidates: number;
+    /** Columns one object may expose to a match. Default 500. */
+    readonly maxColumns: number;
+}
+/** Default resolver tuning. */
+export declare const DEFAULT_RESOLVE_OPTIONS: ResolveOptions;
+/** One alias-expanded unit of the entity a user typed. */
+interface Concept {
+    readonly tokens: ReadonlySet<string>;
+}
+/**
+ * Turn the user's entity into the concepts the score is averaged over.
+ *
+ * A matched alias group is one concept (its whole vocabulary is the evidence), and the words the group
+ * did not account for keep their own concepts, so `系统用户` is "user" plus whatever `系统` contributes.
+ * @param entity - what the user typed.
+ * @param aliases - the alias table.
+ * @returns concepts, in a stable order.
+ */
+export declare function buildEntityConcepts(entity: string, aliases: readonly AliasGroup[]): Concept[];
+/**
+ * Resolve a `find` request to an object, its columns, and a parameterized predicate — all offline.
+ * @param db - the open read-only index.
+ * @param engine - the connection's engine, read from the index's `meta`.
+ * @param request - the request to resolve.
+ * @param options - resolver tuning.
+ * @returns the resolution; the caller executes it only when the status is `resolved`.
+ */
+export declare function resolveFind(db: DatabaseSync, engine: string, request: FindRequest, options: ResolveOptions): Resolution;
+export {};
+//# sourceMappingURL=resolve.d.ts.map