@jestek-dev/scripture-engine 0.7.1 → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Freeman
+
+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/README.md

@@ -0,0 +1,35 @@
+# @jestek-dev/scripture-engine
+
+Pure, deterministic Scripture retrieval and ranking core. Zero I/O, zero
+runtime AI, zero dependencies. Every result carries typed reasons and the
+identities that make it reproducible:
+`(engineVersion, corpusFingerprint, layerFingerprint, query)` yields identical
+ordering on every platform.
+
+The engine reads a prebuilt SQLite artifact (`content.db`) through the one
+seam it knows, `ContentQueryPort` — supply it with any SQLite binding
+(`node:sqlite`, OP-SQLite, expo-sqlite):
+
+```ts
+import { createEngine } from '@jestek-dev/scripture-engine';
+import { DatabaseSync } from 'node:sqlite';
+
+const db = new DatabaseSync('content.db', { readOnly: true });
+const engine = await createEngine({
+  async execute(sql, params = []) { return { rows: db.prepare(sql).all(...params) }; },
+  async close() { db.close(); },
+});
+
+const result = await engine.research('hearing and doing');
+```
+
+The artifact ships separately as a
+[GitHub Release asset](https://github.com/jestek-dev/scripture-search-engine/releases),
+alongside a reviewed descriptor. Verify `content.db` against the descriptor's
+`databaseSha256` before opening it.
+
+Full documentation, architecture, data provenance and the admission gauntlet:
+[jestek-dev/scripture-search-engine](https://github.com/jestek-dev/scripture-search-engine).
+
+MIT — the code, not the corpora it is built from; those carry their own terms,
+recorded per source in the repository's `docs/ATTRIBUTIONS.md`.

package/dist/config/engineVersion.d.ts

@@ -8,7 +8,7 @@
  * 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.1";
+export declare const ENGINE_VERSION = "0.14.0";
 /**
  * Bumped independently of ENGINE_VERSION when the tokenizer changes, because
  * a tokenizer change invalidates precomputed corpus term profiles: the

package/dist/config/engineVersion.js

@@ -8,7 +8,53 @@
  * 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.1';
+// 0.9.0: query-coverage scaling, IDF-thin bare-concept cue demotion, and
+// one-significant-word phrase fallback suppression. These alter ordering and reasons.
+// 0.10.0: ranking fixes, staged on one branch and landed as one squash. Stage 1
+// (sole-evidence floor): a result whose only evidence is translation_variant is
+// capped at 6 points — below any honest text match — so a bag-of-stems hint can
+// accompany but never hold #1 alone. Later 0.10.0 stages ride this same bump.
+// 0.11.0 (QR-4): reference-grammar extension. Space-separated chapter/verse
+// resolves ("John 3 16"); un-resolving books earn a cited did-you-mean
+// suggestion (suggestion only, never auto-resolve); bare-number dead ends fall
+// through to discovery; the verse-1 range-label defect is fixed ("John 3:1-5"
+// no longer labeled "John 3"). Kind flips and label changes are
+// results-visible, so this bumps in the same commit as the behavior.
+// 0.12.0 (QR-5): deterministic cited spelling correction, with artifact
+// schema v7 (spelling_terms/spelling_deletes precomputed by the pipeline;
+// curated_aliases shipped empty for QR-6). research() discovery substitutes
+// the unique in-policy correction for tokens in NO vocabulary — bounded
+// integer Damerau under the ONE edit-policy table — and every substitution is
+// cited (token chips + the additive `corrections` list). Substituted tokens
+// change which verses surface and how they are explained, so this bumps in
+// the same commit as the behavior and the schema.
+// 0.13.0 (QR-6): curated phrase/hymn aliases (no schema bump — the
+// curated_aliases table shipped EMPTY in v7 and the engine probes
+// presence-and-rows). research() discovery matches the TYPED query's
+// normalizedPhrase (stopwords kept) against curated_aliases by whole-string
+// EQUALITY — never containment — and surfaces the target concept's own
+// curated anchors (or the named verse range) under the existing
+// concept_anchor family with a full attribution chip
+// (`Hymn: "<title>" → Theme: <label>`). New evidence on alias-keyed queries
+// is results-visible, so this bumps in the same commit as the behavior;
+// non-alias queries are untouched by construction (equality matching).
+// Rollback: rebuild the artifact without alias rows (the probe reverts
+// behavior); an engine revert is a new version.
+// 0.14.0 (CO-3 PR 2): passage-level grouping over the schema-v8 pericope
+// tiling. discover() merges ungoverned results that are consecutive in rank,
+// verseId-consecutive, and members of ONE derived pericope into a single
+// passage row; the existing curated-anchor collapse is unchanged in its
+// merge rule but both mechanisms now EXPLAIN the merge — merged rows carry
+// additive `verses[]` (per-member evidence, uncollapsed) and a typed
+// `grouping` naming the section span and its source (anchor sources for
+// anchor runs, 'openbible-sections' + the summed boundary vote for pericope
+// runs; grouping is not a Reason and contributes zero points). Authority
+// order is fixed: an anchor-claimed verse never joins a pericope run.
+// Merged pericope rows change which rows the default page shows, so this
+// bumps in the same commit as the behavior. Rollback: rebuild the artifact
+// without pericope rows (the presence-and-rows probe reverts the pericope
+// path); an engine revert is a new version.
+export const ENGINE_VERSION = '0.14.0';
 /**
  * Bumped independently of ENGINE_VERSION when the tokenizer changes, because
  * a tokenizer change invalidates precomputed corpus term profiles: the

package/dist/corpus/repository.d.ts

@@ -6,7 +6,7 @@
  * 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 BookAliasEntry, 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;
@@ -41,6 +41,32 @@ export interface TokenMatch extends ScriptureVerse {
     /** Distinct significant tokens in this verse — the precision denominator. */
     readonly distinctTokenCount: number;
 }
+/**
+ * One derived pericope (schema v8, CO-3 PR 1). `boundaryVotes` is the
+ * summed boundary vote at `startVerseId` — a countable structural fact
+ * (how many of the 20 surveyed translations start a section there), never
+ * a relevance score.
+ */
+export interface PericopeRow {
+    readonly startVerseId: number;
+    readonly endVerseId: number;
+    readonly boundaryVotes: number;
+    readonly sourceId: string;
+}
+/**
+ * One mined cross-reference phrase triple (schema v9, B3 Phase A). The
+ * `normalizedPhrase` is the tokenizer-normalized key of the TSK entry
+ * fragment under which the reference was printed — a lookup key, never
+ * displayed prose. Structural lineage only: the row says a curated source
+ * printed this link under that phrase; it scores nothing by itself.
+ */
+export interface CrossReferencePhraseRow {
+    readonly fromVerseId: number;
+    readonly normalizedPhrase: string;
+    readonly toStartVerseId: number;
+    readonly toEndVerseId: number;
+    readonly sourceId: string;
+}
 export interface CorpusMeta {
     readonly schemaVersion: string;
     readonly tokenizerVersion: string;
@@ -58,6 +84,15 @@ export interface CorpusMeta {
 export declare class CorpusRepository implements ReferenceResolver {
     private readonly database;
     constructor(database: ContentQueryPort);
+    /**
+     * The alias vocabulary for the reference did-you-mean (0.11.0/QR-4),
+     * fetched through the port once per repository instance and cached: ~270
+     * rows that cannot change under a running engine (the artifact is
+     * immutable), so re-reading them per query would be waste, and caching
+     * keeps the engine's no-I/O covenant intact — the ONE read still goes
+     * through ContentQueryPort.
+     */
+    private bookAliasCache;
     close(): Promise<void>;
     readMeta(): Promise<CorpusMeta>;
     /** Total indexed verses per translation — the N in IDF. */
@@ -65,7 +100,8 @@ export declare class CorpusRepository implements ReferenceResolver {
     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>;
+    listBookAliases(): Promise<readonly BookAliasEntry[]>;
+    resolveReference(input: string): Promise<import("../internal.js").ReferenceResolutionAttempt>;
     loadPassage(resolved: ResolvedReference): Promise<ScripturePassage>;
     /**
      * Exact phrase via FTS5, ranked by bm25.
@@ -89,6 +125,79 @@ export declare class CorpusRepository implements ReferenceResolver {
      */
     searchTokens(tokens: readonly string[], documentCount: number, limit?: number): Promise<readonly TokenMatch[]>;
     tokenDocumentCounts(tokens: readonly string[]): Promise<ReadonlyMap<string, number>>;
+    /**
+     * Whether this artifact carries the precomputed spelling index
+     * (schema v7, 0.12.0/QR-5). Presence-probed like the other optional
+     * layers: a v6 artifact simply has no tables, the probe returns false, and
+     * the engine gracefully does not correct — behaving exactly as the
+     * pre-spelling engine did. That probe IS the rollback story: rebuild the
+     * artifact without the tables and behavior reverts with no engine change.
+     */
+    hasSpellingIndex(): Promise<boolean>;
+    /**
+     * Whether this artifact carries the derived pericope tiling (schema v8,
+     * CO-3 PR 1). Presence-and-rows probed like the other optional layers: a
+     * v7 artifact has no table, an emptied table disables the (future)
+     * grouping step silently, and behavior reverts to pre-pericope output
+     * with no engine change — the probe IS the rollback story.
+     */
+    hasPericopes(): Promise<boolean>;
+    /**
+     * The pericopes containing any of the given verse ids, batched as ONE
+     * bounded query over the ranked window (G11): the window's min..max verse
+     * span overlaps few pericopes, and the caller maps verses to rows. Rows
+     * come back ordered by start verse for platform-stable iteration.
+     *
+     * NO CALL SITES in discover() yet (CO-3 PR 1 capability): the grouping
+     * behavior that consumes this lands with the PR 2 ENGINE_VERSION bump.
+     * boundaryVotes is the summed boundary vote at the pericope's start verse
+     * — the countable fact the artifact stores, so a future explanation and
+     * the shipped data cannot disagree.
+     */
+    pericopesContaining(verseIds: readonly number[]): Promise<readonly PericopeRow[]>;
+    /**
+     * Whether this artifact carries the mined TSK cross-reference phrase keys
+     * (schema v9, B3 Phase A). Presence-and-rows probed like pericopes: a v8
+     * artifact has no table, an emptied table reads false, and (future)
+     * phrase-labeled behavior reverts to plain cross_references output with no
+     * engine change — the probe IS the rollback story.
+     */
+    hasCrossReferencePhrases(): Promise<boolean>;
+    /**
+     * The cross-reference phrase triples whose FROM verse is one of the given
+     * verse ids, batched as ONE bounded query over the window's min..max span
+     * (G11) and filtered back to the asked-for verses. Rows come back ordered
+     * by (from, phrase, start, end, source) for platform-stable iteration —
+     * sorted HERE, in engine code, by UTF-16 code units (the same comparison
+     * buildConceptLayer's fingerprint feed uses), never by the port's SQL
+     * collation: SQLite's BINARY collation compares UTF-8 bytes, which
+     * disagrees with JS on some non-ASCII strings, and the ordering contract
+     * must not depend on which side compares.
+     *
+     * NO CALL SITES in discover() yet (B3 Phase A capability): the labeling
+     * and off-phrase-discount behavior that consumes this lands with the
+     * Phase B ENGINE_VERSION bump behind J26/J55.
+     */
+    crossReferencePhrasesFor(verseIds: readonly number[]): Promise<readonly CrossReferencePhraseRow[]>;
+    /**
+     * Which of the given tokens exist in the artifact's spelling vocabulary
+     * (corpus tokens ∪ book aliases ∪ lexicon tokens ∪ translation tokens ∪
+     * Layer B verse terms).
+     * This is the OOV gate's second half: a token with corpus df 0 that is
+     * still a known name or curated word is IN vocabulary and never corrected.
+     */
+    spellingTermsPresent(tokens: readonly string[]): Promise<ReadonlySet<string>>;
+    /**
+     * Dictionary terms whose precomputed delete variants intersect the given
+     * keys — the SymSpell candidate lookup (0.12.0/QR-5). Proposes only: every
+     * candidate is re-verified with the bounded Damerau DP before it may win
+     * (see intents/spelling.ts). ORDER BY term for a platform-stable row order,
+     * though the picker is proven row-order independent anyway.
+     */
+    spellingCandidates(deleteKeys: readonly string[]): Promise<readonly {
+        term: string;
+        documentCount: number;
+    }[]>;
 }
 /**
  * Finds the LONGEST verbatim fragment of the query present in the corpus.
@@ -121,6 +230,18 @@ export interface ConceptAnchorRow extends ScriptureVerse {
     readonly sourceId: string;
     readonly weight: number;
     readonly locator: string | null;
+    /**
+     * The curated anchor's OWN span, carried through so results can be presented
+     * as the passage a human named rather than as N separate verses.
+     *
+     * A ranged anchor emits one candidate per verse, and authoritative results
+     * are exempt from group diversification by design — so `communion` returned
+     * 1 Cor 11:23, :24, :25 and :26 as four identical-scoring results occupying
+     * the whole top of the list. The span is the natural unit here because a
+     * human chose it; nothing has to be inferred.
+     */
+    readonly anchorStartVerseId: number;
+    readonly anchorEndVerseId: number;
 }
 /** A verse reached by a curated cross-reference edge. */
 export interface CrossReferenceRow extends ScriptureVerse {
@@ -128,6 +249,26 @@ export interface CrossReferenceRow extends ScriptureVerse {
     readonly sourceId: string;
     readonly votes: number;
 }
+/**
+ * One curated phrase/hymn alias (0.13.0/QR-6): a whole-query key mapping to
+ * exactly one of a curated concept or an explicit verse range (the schema's
+ * XOR CHECK). `title` and `locator` surface verbatim in the explanation chip
+ * — the attribution IS the product here (covenant 6: the engine reports that
+ * a named source connects this phrase to this target; it adjudicates
+ * nothing).
+ */
+export interface CuratedAliasRow {
+    readonly id: number;
+    readonly title: string;
+    readonly conceptId: string | null;
+    /** Label of the target concept; null exactly when conceptId is null. */
+    readonly conceptLabel: string | null;
+    readonly startVerseId: number | null;
+    readonly endVerseId: number | null;
+    readonly sourceId: string;
+    readonly weight: number;
+    readonly locator: string | null;
+}
 /**
  * Concept lookup and anchor expansion — Layer A at query time.
  *
@@ -181,6 +322,26 @@ export declare class ConceptRepository {
      * 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.
      */
+    /**
+     * Verses whose CROSS-TRANSLATION vocabulary matches the query.
+     *
+     * This is what lets someone search in the translation they learned a verse
+     * in. The stems here appear in some English translation of the verse but not
+     * in the one shipped, so a query using that wording reaches the verse
+     * anyway. See pipeline/src/schema.ts for what is and is not stored.
+     *
+     * Ranked by how MANY query stems a verse accounts for, then by verse id. No
+     * IDF weighting: these stems are already the residue after the shipped
+     * wording is subtracted, so a stem appearing here is by construction
+     * something the shipped text does not say.
+     */
+    searchTranslationTokens(tokens: readonly string[], limit?: number): Promise<readonly (ScriptureVerse & {
+        matchedTokens: readonly string[];
+    })[]>;
+    /** How many verses carry each stem — the df for weighting alternate wording. */
+    translationTokenDocumentCounts(tokens: readonly string[]): Promise<ReadonlyMap<string, number>>;
+    /** Whether the artifact carries cross-translation vocabulary at all. */
+    hasTranslationTokens(): Promise<boolean>;
     searchPassageTerms(terms: readonly string[], limit?: number): Promise<readonly (ScriptureVerse & {
         matchedTerms: readonly string[];
         pmiSum: number;
@@ -189,5 +350,31 @@ export declare class ConceptRepository {
         locator: string;
     })[]>;
     hasPassageTerms(): Promise<boolean>;
+    /**
+     * Whether this artifact carries any curated phrase/hymn aliases
+     * (0.13.0/QR-6). Presence-AND-ROWS probed, deliberately stricter than the
+     * other layer probes: schema v7 ships the table EMPTY (QR-5), and an
+     * engine that ran the alias step against an empty table would pay a query
+     * per research() call for nothing — and, more importantly, the rollback
+     * story is "rebuild without alias rows", which must restore pre-QR-6
+     * behavior exactly. No table, or an empty one, and 0.13.0 behaves as
+     * 0.12.0 did.
+     */
+    hasCuratedAliases(): Promise<boolean>;
+    /**
+     * The curated aliases whose whole-query key equals the given normalized
+     * phrase. EQUALITY, never containment — the line that keeps a curated
+     * phrase table from becoming a hidden second ranking system; brittleness
+     * to extra words is accepted BY DESIGN. `normalized_raw` is UNIQUE, so
+     * this returns at most one row; it is typed as a list so the caller does
+     * not encode that schema fact.
+     */
+    matchAliases(normalizedQuery: string): Promise<readonly CuratedAliasRow[]>;
+    /**
+     * Verses of an explicit alias verse range (the XOR's other arm). A range
+     * absent from this corpus returns no rows — the alias then contributes
+     * nothing, honestly, rather than being guessed at.
+     */
+    aliasRangeVerses(startVerseId: number, endVerseId: number): Promise<readonly ScriptureVerse[]>;
     hasConceptLayer(): Promise<boolean>;
 }