@jestek-dev/scripture-engine 0.7.0

package/dist/config/engineVersion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The engine version participates in the reproducibility contract:
+ *
+ *   (engineVersion, corpusFingerprint, layerFingerprint, query)
+ *     -> identical ordering
+ *
+ * Any change that can alter ordering — weights, caps, tokenizer rules,
+ * tie-breaks — MUST bump this in the same commit. Gate G2 fails a PR whose
+ * ordering changed without a bump, so this is enforced, not merely asked for.
+ */
+export declare const ENGINE_VERSION = "0.7.0";
+/**
+ * Bumped independently of ENGINE_VERSION when the tokenizer changes, because
+ * a tokenizer change invalidates precomputed corpus term profiles: the
+ * pipeline and the runtime must tokenize identically or scoring silently
+ * compares mismatched vocabularies. The pipeline stamps this into the
+ * artifact and the engine refuses an artifact built with a different value.
+ */
+export declare const TOKENIZER_VERSION = "1.0.0";

package/dist/config/engineVersion.js

@@ -0,0 +1,19 @@
+/**
+ * The engine version participates in the reproducibility contract:
+ *
+ *   (engineVersion, corpusFingerprint, layerFingerprint, query)
+ *     -> identical ordering
+ *
+ * Any change that can alter ordering — weights, caps, tokenizer rules,
+ * tie-breaks — MUST bump this in the same commit. Gate G2 fails a PR whose
+ * ordering changed without a bump, so this is enforced, not merely asked for.
+ */
+export const ENGINE_VERSION = '0.7.0';
+/**
+ * Bumped independently of ENGINE_VERSION when the tokenizer changes, because
+ * a tokenizer change invalidates precomputed corpus term profiles: the
+ * pipeline and the runtime must tokenize identically or scoring silently
+ * compares mismatched vocabularies. The pipeline stamps this into the
+ * artifact and the engine refuses an artifact built with a different value.
+ */
+export const TOKENIZER_VERSION = '1.0.0';

package/dist/corpus/repository.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Corpus access. The only module that knows SQL.
+ *
+ * Ported from Maskil's `ScriptureRepository` and extended with the token
+ * postings this engine adds. Everything here returns plain data; scoring
+ * lives in `ranking/`, so the ranker stays pure and unit-testable without a
+ * database.
+ */
+import { type ReferenceResolver, type ResolvedBook, type ResolvedReference } from '../reference/reference.js';
+import type { ContentQueryPort, ScripturePassage, ScriptureVerse } from '../types.js';
+export declare const MAX_PHRASE_LENGTH = 500;
+export declare const MAX_CANDIDATES = 200;
+/** One verse that matched a phrase query, with its bm25 relevance. */
+export interface PhraseMatch extends ScriptureVerse {
+    /** SQLite bm25: more negative is more relevant. Normalized by the caller. */
+    readonly bm25: number;
+}
+/** The longest verbatim fragment of a query that occurs in the corpus. */
+export interface PhraseFragmentResult {
+    /** The fragment that matched, as the user wrote it. */
+    readonly fragment: string;
+    /** Words in the fragment. */
+    readonly fragmentWords: number;
+    /** Words in the whole query — the denominator for partial-match strength. */
+    readonly queryWords: number;
+    readonly matches: readonly PhraseMatch[];
+}
+/** One verse that matched at least one query token. */
+export interface TokenMatch extends ScriptureVerse {
+    /** Distinct query tokens present in this verse. */
+    readonly matchedTokens: readonly string[];
+    /** Sum of IDF over matched tokens — rare words contribute more. */
+    readonly idfSum: number;
+    /**
+     * Smallest window (in raw word positions) containing all matched tokens.
+     * Null when only one token matched, since a single point has no span.
+     */
+    readonly minSpan: number | null;
+    /** Total significant tokens in this verse. */
+    readonly tokenCount: number;
+    /** Distinct significant tokens in this verse — the precision denominator. */
+    readonly distinctTokenCount: number;
+}
+export interface CorpusMeta {
+    readonly schemaVersion: string;
+    readonly tokenizerVersion: string;
+    readonly corpusFingerprint: string;
+    readonly verseCount: number;
+    /** Mean significant-token length per verse — the avgdl of length normalization. */
+    readonly avgVerseTokens: number;
+    /**
+     * Identity of the curated layers. Empty string when an artifact has no
+     * concept layer, which is a legitimate state (a v1 lexical-only artifact),
+     * not a missing value.
+     */
+    readonly layerFingerprint: string;
+}
+export declare class CorpusRepository implements ReferenceResolver {
+    private readonly database;
+    constructor(database: ContentQueryPort);
+    close(): Promise<void>;
+    readMeta(): Promise<CorpusMeta>;
+    /** Total indexed verses per translation — the N in IDF. */
+    documentCount(): Promise<number>;
+    resolveBookAlias(aliasKey: string): Promise<ResolvedBook | null>;
+    getChapterVerseCount(bookId: number, chapter: number): Promise<number | null>;
+    verseExists(bookId: number, chapter: number, verse: number): Promise<boolean>;
+    resolveReference(input: string): Promise<import("../index.js").ReferenceResolutionAttempt>;
+    loadPassage(resolved: ResolvedReference): Promise<ScripturePassage>;
+    /**
+     * Exact phrase via FTS5, ranked by bm25.
+     *
+     * Runs against the RAW verse text, not our token stream, because "exact"
+     * must mean exact — a user asking for a verbatim phrase does not want
+     * stemming or archaic folding applied behind their back. The token intent
+     * is where fuzziness is allowed, and it says so in its reason label.
+     */
+    searchPhrase(phrase: string, limit?: number): Promise<readonly PhraseMatch[]>;
+    /**
+     * Token search over precomputed postings.
+     *
+     * This is the intent that makes theme-ish queries work before any concept
+     * layer exists: query tokens are folded by the same tokenizer the corpus
+     * was indexed with, so "hearing and doing" reaches "heareth ... doeth".
+     *
+     * IDF is computed from stored document counts, which is why keeping common
+     * words as tokens is safe — "do" earns a near-zero weight automatically
+     * instead of needing a stopword list to predict its unimportance.
+     */
+    searchTokens(tokens: readonly string[], documentCount: number, limit?: number): Promise<readonly TokenMatch[]>;
+    tokenDocumentCounts(tokens: readonly string[]): Promise<ReadonlyMap<string, number>>;
+}
+/**
+ * Finds the LONGEST verbatim fragment of the query present in the corpus.
+ *
+ * Users paraphrase. "be doers of the word not hearers only" is nobody's
+ * translation verbatim, but "doers of the word" is exactly James 1:22 — and
+ * a search that only tries the whole query throws that away, leaving the
+ * decision to weaker signals.
+ *
+ * Longest-first with early exit: the first fragment length that matches wins,
+ * so we never pay for shorter, vaguer fragments once a strong one is found.
+ * Strength is computed by the caller as fragmentWords / queryWords, which
+ * makes partial verbatim evidence proportional to how much of the question it
+ * actually answers — a full verbatim match still earns full authority.
+ */
+export declare function searchLongestFragment(repository: CorpusRepository, query: string, limit?: number): Promise<PhraseFragmentResult | null>;
+/** A concept whose lexicon matched the query. */
+export interface ConceptMatchRow {
+    readonly conceptId: string;
+    readonly label: string;
+    /** The author's original phrase that matched — shown, not the normalized form. */
+    readonly matchedPhrase: string;
+    /** Tokens in the matched phrase; longer phrases are more specific evidence. */
+    readonly matchedTokenCount: number;
+}
+/** A verse named by a concept, with the source that named it. */
+export interface ConceptAnchorRow extends ScriptureVerse {
+    readonly conceptId: string;
+    readonly conceptLabel: string;
+    readonly sourceId: string;
+    readonly weight: number;
+    readonly locator: string | null;
+}
+/** A verse reached by a curated cross-reference edge. */
+export interface CrossReferenceRow extends ScriptureVerse {
+    readonly fromVerseId: number;
+    readonly sourceId: string;
+    readonly votes: number;
+}
+/**
+ * Concept lookup and anchor expansion — Layer A at query time.
+ *
+ * Kept in the repository (not the intents module) because it is SQL; the
+ * scoring decisions live in `intents/concept.ts` so they stay pure.
+ */
+export declare class ConceptRepository {
+    private readonly database;
+    constructor(database: ContentQueryPort);
+    /**
+     * Concepts whose lexicon phrase is fully contained in the query's tokens.
+     *
+     * Containment, not similarity: "hearing and doing" (tokens hear, do) fires
+     * the concept because every token of the lexicon phrase is present. A
+     * fuzzy threshold here would be a second, hidden ranking system competing
+     * with the real one — the lexicon is curated precisely so matching can be
+     * exact and explainable.
+     */
+    matchConcepts(queryTokens: readonly string[]): Promise<readonly ConceptMatchRow[]>;
+    /** Verses anchored by the given concepts. */
+    anchorVerses(conceptIds: readonly string[]): Promise<readonly ConceptAnchorRow[]>;
+    /**
+     * The reverse of anchorVerses: which curated concepts name THIS passage?
+     *
+     * Powers `related()`, whose contract is "what did a human connect to this
+     * text", not "what resembles it". An anchor overlapping the passage at all
+     * counts, because a concept anchored to James 1:22-25 is about James 1:23
+     * even though it does not name that verse alone.
+     */
+    conceptsAnchoring(startVerseId: number, endVerseId: number): Promise<readonly {
+        conceptId: string;
+        label: string;
+    }[]>;
+    /** Concepts one hop away in the curated graph. */
+    relatedConcepts(conceptIds: readonly string[]): Promise<readonly string[]>;
+    /**
+     * Verses reached by cross-reference from the given seed verses.
+     *
+     * Bounded per seed: an unbounded expansion would let one well-connected
+     * verse flood the candidate set, which is precision erosion by another
+     * name.
+     */
+    expandCrossReferences(fromVerseIds: readonly number[], perSeedLimit?: number): Promise<readonly CrossReferenceRow[]>;
+    /** Highest observed vote count, used to normalize vote-derived strength. */
+    maxCrossReferenceVotes(): Promise<number>;
+    /**
+     * Verses whose pericope profile contains query terms (Layer B).
+     *
+     * Weak evidence by design and by budget: a preacher using a word while
+     * expounding a passage is real signal about what the passage is ABOUT, but
+     * it is a long way from the passage saying it. G6 caps it so no volume of
+     * homiletical vocabulary can outrank a curated anchor or a verbatim quote.
+     */
+    searchPassageTerms(terms: readonly string[], limit?: number): Promise<readonly (ScriptureVerse & {
+        matchedTerms: readonly string[];
+        pmiSum: number;
+        sourceIds: string;
+        minSpanVerses: number;
+        locator: string;
+    })[]>;
+    hasPassageTerms(): Promise<boolean>;
+    hasConceptLayer(): Promise<boolean>;
+}