@jestek-dev/scripture-engine 0.7.0

package/dist/intents/lexical.js

@@ -0,0 +1,136 @@
+/**
+ * Lexical intents — steps 2, 3 and 4 of the ladder (exact phrase, distinctive
+ * tokens with proximity, conservative normalization).
+ *
+ * Each intent's job is to turn corpus rows into typed Evidence. It never
+ * decides ordering; the ranker does, under the signal budgets. That split is
+ * what keeps "add a new intent" from being able to destabilize ranking.
+ */
+import { significantWords } from '../tokenizer/index.js';
+/**
+ * Canonical, sortable target id: zero-padded so lexicographic order IS
+ * scripture order. The ranker uses targetId as its final tie-break, so this
+ * padding is what makes equal-scoring results present in Genesis-to-
+ * Revelation order rather than string-sorted nonsense ("10" before "9").
+ */
+export function targetIdFor(verse) {
+    return `${verse.translationCode}:${String(verse.verseId).padStart(8, '0')}`;
+}
+/** Chapter-level grouping — the unit diversification thins by. */
+export function groupIdFor(verse) {
+    return `${verse.translationCode}:${verse.bookId}:${verse.chapter}`;
+}
+export function referenceLabel(verse) {
+    return `${verse.bookName} ${verse.chapter}:${verse.verse}`;
+}
+/**
+ * Exact phrase evidence.
+ *
+ * Strength is BINARY: a verse either contains the phrase or it does not, and
+ * pretending otherwise would put a confidence gradient on a yes/no fact.
+ * bm25 is used upstream to choose WHICH matches survive the candidate cap
+ * when there are more than the limit, but it never modulates strength — so
+ * equal-strength matches fall through to the canonical-order tie-break,
+ * which is what a reader expects from a concordance-style result.
+ */
+export function phraseEvidence(fragment, fragmentWords, queryWords) {
+    const complete = fragmentWords >= queryWords;
+    return {
+        family: 'exact_phrase',
+        label: complete ? 'Exact phrase' : `Contains "${fragment}"`,
+        // Proportional to how much of the question this verbatim text answers.
+        // A whole-query match earns full authority; a four-word fragment of an
+        // eight-word paraphrase earns half. This is what lets a paraphrase like
+        // "be doers of the word not hearers only" still resolve decisively to
+        // James 1:22, without pretending a fragment is the whole quotation.
+        strength: Math.max(0, Math.min(1, fragmentWords / Math.max(1, queryWords))),
+    };
+}
+const PROXIMITY_WINDOW = 20;
+/**
+ * Additive smoothing for the precision term. Keeps a very short verse from
+ * scoring high precision on one incidental shared word.
+ */
+const PRECISION_SMOOTHING = 2;
+/**
+ * Token-overlap and proximity evidence.
+ *
+ * Coverage is IDF-weighted rather than a raw count: matching "refuge" and
+ * "strength" is worth far more than matching "do" and "one", and weighting
+ * by inverse document frequency expresses that without anyone having to
+ * hand-maintain a list of which words are important.
+ */
+export function tokenEvidence(match, queryIdfTotal) {
+    const evidence = [];
+    const coverage = queryIdfTotal > 0 ? Math.min(1, match.idfSum / queryIdfTotal) : 0;
+    if (coverage <= 0)
+        return evidence;
+    // Coverage alone is RECALL — "did the verse contain what I asked for?" —
+    // and it saturates at 1.0 for every verse containing all the query's
+    // terms. That is how Luke 6:47 tied with (and then beat) James 1:22 for
+    // "be doers of the word not hearers only": both contain hear + do + word,
+    // so both scored a perfect 1.0.
+    //
+    // Precision is the missing half: what fraction of the VERSE is what you
+    // asked about? James 1:22 is five significant words, three of them yours;
+    // Luke 6:47 is seven, three of them yours. The first is more ABOUT the
+    // query even though both contain it.
+    //
+    // Smoothed by PRECISION_SMOOTHING so that very short verses do not win by
+    // arithmetic accident — without it a two-word verse sharing one word would
+    // score 0.5 precision on almost no evidence.
+    const precision = (match.matchedTokens.length + PRECISION_SMOOTHING) /
+        (Math.max(match.matchedTokens.length, match.distinctTokenCount) + PRECISION_SMOOTHING);
+    evidence.push({
+        family: 'token_overlap',
+        label: match.matchedTokens.length === 1
+            ? `Shared word: ${match.matchedTokens[0]}`
+            : `Shared words: ${match.matchedTokens.join(', ')}`,
+        strength: coverage * precision,
+    });
+    // Proximity only means something with two or more matched tokens. The
+    // ideal span for n tokens is n-1 (adjacent words); anything wider decays
+    // linearly to zero at PROXIMITY_WINDOW words apart.
+    if (match.minSpan !== null && match.matchedTokens.length > 1) {
+        const ideal = match.matchedTokens.length - 1;
+        const excess = Math.max(0, match.minSpan - ideal);
+        const strength = Math.max(0, 1 - excess / PROXIMITY_WINDOW);
+        if (strength > 0) {
+            evidence.push({
+                family: 'proximity',
+                label: 'Matched words appear close together',
+                strength,
+            });
+        }
+    }
+    return evidence;
+}
+/** Total IDF of the query's tokens — the denominator for coverage. */
+export function queryIdfTotal(tokens, documentFrequencies, documentCount) {
+    return [...new Set(tokens)].reduce((sum, token) => {
+        const df = documentFrequencies.get(token) ?? 0;
+        return sum + Math.log(1 + documentCount / Math.max(1, df));
+    }, 0);
+}
+/** Merge per-verse evidence from every lexical intent into ranked candidates. */
+export function mergeCandidates(contributions) {
+    const byTarget = new Map();
+    for (const contribution of contributions) {
+        const key = targetIdFor(contribution.verse);
+        const existing = byTarget.get(key);
+        if (existing)
+            existing.evidence.push(...contribution.evidence);
+        else
+            byTarget.set(key, { verse: contribution.verse, evidence: [...contribution.evidence] });
+    }
+    // Sorted by key so candidate construction order is deterministic regardless
+    // of which intent happened to see a verse first.
+    return [...byTarget.entries()]
+        .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+        .map(([targetId, entry]) => ({
+        targetId,
+        groupId: groupIdFor(entry.verse),
+        evidence: entry.evidence,
+    }));
+}
+export { significantWords };

package/dist/ranking/budgets.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SIGNAL BUDGETS — guardrail G6, the deepest guardrail in the system.
+ *
+ * Every other gate measures whether a data addition made results worse.
+ * This one makes the worst case BOUNDED BY CONSTRUCTION: because these caps
+ * are enforced inside the scoring core rather than assumed by convention, an
+ * admitted dataset cannot shout down an exact match or a curated anchor no
+ * matter how large it is. Adding data changes WHICH candidates surface; it
+ * can never change HOW LOUD a signal class is permitted to be.
+ *
+ * That bound is what makes it safe to keep feeding the system over time: a
+ * bad addition can waste space and add mediocre candidates (which G4, G5, G8
+ * and G9 catch), but it cannot invert the evidence hierarchy.
+ *
+ * These numbers are reviewed data. Changing one changes ordering, so gate G2
+ * requires an ENGINE_VERSION bump in the same commit, and the golden corpus
+ * (G3) plus noise probes (G8) must still pass.
+ */
+import type { Evidence, Reason, SignalFamily } from '../reasons/types.js';
+export interface FamilyBudget {
+    /** Points awarded at strength 1.0. */
+    readonly maxPoints: number;
+    /**
+     * Most reasons of this family that may contribute to a single result.
+     * Ten sermons agreeing is not ten independent facts.
+     */
+    readonly maxReasons: number;
+}
+export interface SignalBudgets {
+    readonly families: Readonly<Record<SignalFamily, FamilyBudget>>;
+    /**
+     * Ceiling on the SUM of all weak-family points for one result. This is the
+     * rule that keeps accumulated weak evidence from ever equalling direct
+     * evidence: no pile of thematic hints outranks a verbatim phrase match.
+     */
+    readonly weakAggregateCap: number;
+    /**
+     * Families whose evidence derives from overlapping upstream data share one
+     * budget (guardrail G7). OpenBible's cross-references derive largely from
+     * TSK, and homiletical co-citations overlap both; counting them as
+     * independent would inflate confidence for what is substantially one fact.
+     */
+    readonly correlationGroups: readonly (readonly SignalFamily[])[];
+}
+export declare const DEFAULT_BUDGETS: SignalBudgets;
+export interface BudgetedScore {
+    readonly score: number;
+    readonly reasons: readonly Reason[];
+    /** True when any cap actually reduced a contribution — surfaced in gate reports. */
+    readonly capped: boolean;
+}
+/**
+ * Apply the budgets to one candidate's raw evidence.
+ *
+ * Order of operations matters and is fixed:
+ *   1. per-family reason count cap (drop the weakest duplicates)
+ *   2. per-family point cap (via maxPoints scaling)
+ *   3. correlation-group cap (correlated families share the larger budget)
+ *   4. weak aggregate cap (scale all weak reasons proportionally)
+ *
+ * Scaling proportionally rather than truncating keeps the relative ordering
+ * of weak reasons intact, so the displayed explanation still ranks the same
+ * way the evidence does.
+ */
+export declare function applyBudgets(evidence: readonly Evidence[], budgets?: SignalBudgets): BudgetedScore;

package/dist/ranking/budgets.js

@@ -0,0 +1,149 @@
+/**
+ * SIGNAL BUDGETS — guardrail G6, the deepest guardrail in the system.
+ *
+ * Every other gate measures whether a data addition made results worse.
+ * This one makes the worst case BOUNDED BY CONSTRUCTION: because these caps
+ * are enforced inside the scoring core rather than assumed by convention, an
+ * admitted dataset cannot shout down an exact match or a curated anchor no
+ * matter how large it is. Adding data changes WHICH candidates surface; it
+ * can never change HOW LOUD a signal class is permitted to be.
+ *
+ * That bound is what makes it safe to keep feeding the system over time: a
+ * bad addition can waste space and add mediocre candidates (which G4, G5, G8
+ * and G9 catch), but it cannot invert the evidence hierarchy.
+ *
+ * These numbers are reviewed data. Changing one changes ordering, so gate G2
+ * requires an ENGINE_VERSION bump in the same commit, and the golden corpus
+ * (G3) plus noise probes (G8) must still pass.
+ */
+import { isAuthoritative } from '../reasons/types.js';
+export const DEFAULT_BUDGETS = {
+    families: {
+        // Authoritative — these dominate by design.
+        reference: { maxPoints: 100, maxReasons: 1 },
+        exact_phrase: { maxPoints: 60, maxReasons: 1 },
+        concept_anchor: { maxPoints: 40, maxReasons: 3 },
+        // Weak — individually modest, collectively capped below.
+        concept_lexicon: { maxPoints: 12, maxReasons: 2 },
+        token_overlap: { maxPoints: 10, maxReasons: 1 },
+        proximity: { maxPoints: 6, maxReasons: 1 },
+        passage_terms: { maxPoints: 8, maxReasons: 2 },
+        cross_reference: { maxPoints: 6, maxReasons: 2 },
+        co_citation: { maxPoints: 5, maxReasons: 2 },
+    },
+    // Deliberately below exact_phrase.maxPoints: every weak signal in the
+    // system, all firing at full strength, still loses to one verbatim match.
+    weakAggregateCap: 30,
+    correlationGroups: [['cross_reference', 'co_citation']],
+};
+function toReason(evidence, budget) {
+    const clampedStrength = Math.min(1, Math.max(0, evidence.strength));
+    return {
+        family: evidence.family,
+        label: evidence.label,
+        points: clampedStrength * budget.maxPoints,
+        ...(evidence.provenance ? { provenance: evidence.provenance } : {}),
+    };
+}
+/**
+ * Deterministic evidence ordering. Sorting by strength alone would let two
+ * equal-strength items from different sources swap places between builds,
+ * which would break the reproducibility contract; family name then label
+ * then locator give a total order over otherwise-tied evidence.
+ */
+function compareEvidence(a, b) {
+    if (b.strength !== a.strength)
+        return b.strength - a.strength;
+    if (a.family !== b.family)
+        return a.family < b.family ? -1 : 1;
+    if (a.label !== b.label)
+        return a.label < b.label ? -1 : 1;
+    const aLoc = a.provenance?.locator ?? '';
+    const bLoc = b.provenance?.locator ?? '';
+    if (aLoc !== bLoc)
+        return aLoc < bLoc ? -1 : 1;
+    const aSrc = a.provenance?.sourceId ?? '';
+    const bSrc = b.provenance?.sourceId ?? '';
+    return aSrc < bSrc ? -1 : aSrc > bSrc ? 1 : 0;
+}
+/**
+ * Apply the budgets to one candidate's raw evidence.
+ *
+ * Order of operations matters and is fixed:
+ *   1. per-family reason count cap (drop the weakest duplicates)
+ *   2. per-family point cap (via maxPoints scaling)
+ *   3. correlation-group cap (correlated families share the larger budget)
+ *   4. weak aggregate cap (scale all weak reasons proportionally)
+ *
+ * Scaling proportionally rather than truncating keeps the relative ordering
+ * of weak reasons intact, so the displayed explanation still ranks the same
+ * way the evidence does.
+ */
+export function applyBudgets(evidence, budgets = DEFAULT_BUDGETS) {
+    let capped = false;
+    // 1 + 2: per-family caps.
+    const byFamily = new Map();
+    for (const item of evidence) {
+        const bucket = byFamily.get(item.family);
+        if (bucket)
+            bucket.push(item);
+        else
+            byFamily.set(item.family, [item]);
+    }
+    const reasons = [];
+    for (const [family, items] of byFamily) {
+        const budget = budgets.families[family];
+        const ordered = [...items].sort(compareEvidence);
+        if (ordered.length > budget.maxReasons)
+            capped = true;
+        for (const item of ordered.slice(0, budget.maxReasons)) {
+            reasons.push(toReason(item, budget));
+        }
+    }
+    // 3: correlation groups — the group's total may not exceed the largest
+    // single member budget, so overlapping sources cannot stack.
+    for (const group of budgets.correlationGroups) {
+        const members = reasons.filter((reason) => group.includes(reason.family));
+        if (members.length < 2)
+            continue;
+        const groupCap = Math.max(...group.map((family) => budgets.families[family].maxPoints));
+        const total = members.reduce((sum, reason) => sum + reason.points, 0);
+        if (total <= groupCap || total === 0)
+            continue;
+        capped = true;
+        const scale = groupCap / total;
+        for (const member of members) {
+            const index = reasons.indexOf(member);
+            reasons[index] = {
+                ...member,
+                points: member.points * scale,
+                uncappedPoints: member.points,
+            };
+        }
+    }
+    // 4: weak aggregate cap.
+    const weak = reasons.filter((reason) => !isAuthoritative(reason.family));
+    const weakTotal = weak.reduce((sum, reason) => sum + reason.points, 0);
+    if (weakTotal > budgets.weakAggregateCap && weakTotal > 0) {
+        capped = true;
+        const scale = budgets.weakAggregateCap / weakTotal;
+        for (const member of weak) {
+            const index = reasons.indexOf(member);
+            reasons[index] = {
+                ...member,
+                points: member.points * scale,
+                uncappedPoints: member.uncappedPoints ?? member.points,
+            };
+        }
+    }
+    // Stable presentation order: strongest first, ties broken by family then label.
+    const ordered = [...reasons].sort((a, b) => {
+        if (b.points !== a.points)
+            return b.points - a.points;
+        if (a.family !== b.family)
+            return a.family < b.family ? -1 : 1;
+        return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+    });
+    const score = ordered.reduce((sum, reason) => sum + reason.points, 0);
+    return { score, reasons: ordered, capped };
+}

package/dist/ranking/rank.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The pure scoring core. Pattern ported from LH Worship Setlist's
+ * `src/lib/reco/engine.ts`: this module imports no database and no corpus
+ * module, takes fully pre-extracted evidence, and is therefore unit-testable
+ * in isolation. Only the orchestrator (`engine/src/index.ts`) touches I/O.
+ *
+ * Determinism is the product here. Same engine version + same corpus
+ * fingerprint + same query MUST yield byte-identical ordering on every
+ * platform, which is why every comparison below ends in a total-order
+ * tie-break and no step depends on input order or Map iteration order.
+ */
+import type { Evidence, Reason } from '../reasons/types.js';
+import { type SignalBudgets } from './budgets.js';
+export interface Candidate {
+    /** Stable target id — the final tie-break, so ordering never wobbles. */
+    readonly targetId: string;
+    /** Pericope or passage grouping key, used for diversification. */
+    readonly groupId: string;
+    readonly evidence: readonly Evidence[];
+}
+export interface RankedResult {
+    readonly targetId: string;
+    readonly groupId: string;
+    readonly score: number;
+    readonly reasons: readonly Reason[];
+    readonly capped: boolean;
+}
+export interface RankOptions {
+    readonly budgets?: SignalBudgets;
+    readonly limit?: number;
+    /**
+     * Most results allowed from one passage group, applied ONLY to results
+     * carrying no authoritative evidence. Per the 2026-07-20 rule, results
+     * "diversify by passage context only after high-confidence direct matches
+     * are protected" — a genuine 6-verse exact-phrase hit in one chapter must
+     * never be thinned for the sake of variety.
+     */
+    readonly maxPerGroup?: number;
+}
+export declare const DEFAULT_LIMIT = 25;
+export declare const DEFAULT_MAX_PER_GROUP = 3;
+export declare function rank(candidates: readonly Candidate[], options?: RankOptions): readonly RankedResult[];

package/dist/ranking/rank.js

@@ -0,0 +1,71 @@
+/**
+ * The pure scoring core. Pattern ported from LH Worship Setlist's
+ * `src/lib/reco/engine.ts`: this module imports no database and no corpus
+ * module, takes fully pre-extracted evidence, and is therefore unit-testable
+ * in isolation. Only the orchestrator (`engine/src/index.ts`) touches I/O.
+ *
+ * Determinism is the product here. Same engine version + same corpus
+ * fingerprint + same query MUST yield byte-identical ordering on every
+ * platform, which is why every comparison below ends in a total-order
+ * tie-break and no step depends on input order or Map iteration order.
+ */
+import { isAuthoritative } from '../reasons/types.js';
+import { applyBudgets, DEFAULT_BUDGETS } from './budgets.js';
+export const DEFAULT_LIMIT = 25;
+export const DEFAULT_MAX_PER_GROUP = 3;
+/**
+ * Total order over scored results: score desc, then authoritative-first (so a
+ * direct match outranks an equal-scoring pile of hints), then targetId asc.
+ * targetId is the documented final tie-break and is unique, so this comparator
+ * never returns 0 for distinct results — no reliance on sort stability.
+ */
+function compareResults(a, b) {
+    if (b.score !== a.score)
+        return b.score - a.score;
+    const aAuth = a.reasons.some((reason) => isAuthoritative(reason.family));
+    const bAuth = b.reasons.some((reason) => isAuthoritative(reason.family));
+    if (aAuth !== bAuth)
+        return aAuth ? -1 : 1;
+    return a.targetId < b.targetId ? -1 : a.targetId > b.targetId ? 1 : 0;
+}
+export function rank(candidates, options = {}) {
+    const budgets = options.budgets ?? DEFAULT_BUDGETS;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const maxPerGroup = options.maxPerGroup ?? DEFAULT_MAX_PER_GROUP;
+    const scored = candidates.map((candidate) => {
+        const { score, reasons, capped } = applyBudgets(candidate.evidence, budgets);
+        return {
+            targetId: candidate.targetId,
+            groupId: candidate.groupId,
+            score,
+            reasons,
+            capped,
+        };
+    });
+    // Drop zero-evidence candidates rather than ranking them arbitrarily.
+    const surviving = scored.filter((result) => result.reasons.length > 0);
+    surviving.sort(compareResults);
+    const groupCounts = new Map();
+    const output = [];
+    const deferred = [];
+    for (const result of surviving) {
+        if (output.length >= limit)
+            break;
+        const authoritative = result.reasons.some((reason) => isAuthoritative(reason.family));
+        const used = groupCounts.get(result.groupId) ?? 0;
+        if (!authoritative && used >= maxPerGroup) {
+            deferred.push(result);
+            continue;
+        }
+        groupCounts.set(result.groupId, used + 1);
+        output.push(result);
+    }
+    // Diversification thins, it never discards: if the capped groups left room
+    // under the limit, deferred results return in their original total order.
+    for (const result of deferred) {
+        if (output.length >= limit)
+            break;
+        output.push(result);
+    }
+    return output;
+}

package/dist/reasons/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed reason objects. Shape ported from LH Worship Setlist's
+ * `RecoReason { kind, label, tone, points }` and extended with the two things
+ * Maskil's plan requires: machine-verifiable evidence and provenance.
+ *
+ * Contract (from the 2026-07-20 ranking rules): every result carries at least
+ * one reason, and every reason must correspond to actual scoring evidence.
+ * A result whose displayed reason does not match the evidence that produced
+ * its score is a gate G3 failure, not a cosmetic bug — the explanation IS the
+ * product. "No result claims the application understood or interpreted the
+ * lyric": reasons state what matched, never what it means.
+ */
+/**
+ * Signal families, in evidence-strength order. The split into authoritative
+ * and weak is not cosmetic — `ranking/budgets.ts` caps the weak families both
+ * individually and in aggregate, which is what structurally prevents a large
+ * new dataset from outranking an exact match (guardrail G6).
+ */
+export type SignalFamily = 'reference' | 'exact_phrase' | 'concept_anchor' | 'concept_lexicon' | 'token_overlap' | 'proximity' | 'passage_terms' | 'cross_reference' | 'co_citation';
+export declare const AUTHORITATIVE_FAMILIES: readonly SignalFamily[];
+export declare function isAuthoritative(family: SignalFamily): boolean;
+/**
+ * Where a piece of evidence came from. Every weak-signal reason must carry
+ * one: it is what lets the UI print "Nave 'Obedience'" or "Spurgeon, MTP
+ * #1467" instead of an unfalsifiable claim of relevance, and what lets gate
+ * G1 prove every shipped row traces to an admitted source.
+ */
+export interface Provenance {
+    /** Manifest source id, e.g. 'openbible-topics', 'nave', 'editorial'. */
+    readonly sourceId: string;
+    /** Human-facing attribution, e.g. "Nave's Topical Bible". */
+    readonly label: string;
+    /** Optional locator within the source: topic name, sermon id, work section. */
+    readonly locator?: string;
+    /** Optional source-defined weight (e.g. OpenBible votes) — a prior, never truth. */
+    readonly weight?: number;
+}
+export interface Reason {
+    readonly family: SignalFamily;
+    /** Short display label, e.g. "Exact phrase", "Theme: hearing and doing". */
+    readonly label: string;
+    /** Points this reason actually contributed AFTER caps were applied. */
+    readonly points: number;
+    /** Points before caps; present only when a cap reduced the contribution. */
+    readonly uncappedPoints?: number;
+    readonly provenance?: Provenance;
+}
+/** Raw evidence produced by an intent, before budgets are applied. */
+export interface Evidence {
+    readonly family: SignalFamily;
+    readonly label: string;
+    /** Raw strength, typically 0..1 within the family; budgets convert to points. */
+    readonly strength: number;
+    readonly provenance?: Provenance;
+}

package/dist/reasons/types.js

@@ -0,0 +1,20 @@
+/**
+ * Typed reason objects. Shape ported from LH Worship Setlist's
+ * `RecoReason { kind, label, tone, points }` and extended with the two things
+ * Maskil's plan requires: machine-verifiable evidence and provenance.
+ *
+ * Contract (from the 2026-07-20 ranking rules): every result carries at least
+ * one reason, and every reason must correspond to actual scoring evidence.
+ * A result whose displayed reason does not match the evidence that produced
+ * its score is a gate G3 failure, not a cosmetic bug — the explanation IS the
+ * product. "No result claims the application understood or interpreted the
+ * lyric": reasons state what matched, never what it means.
+ */
+export const AUTHORITATIVE_FAMILIES = [
+    'reference',
+    'exact_phrase',
+    'concept_anchor',
+];
+export function isAuthoritative(family) {
+    return AUTHORITATIVE_FAMILIES.includes(family);
+}

package/dist/reference/reference.d.ts

@@ -0,0 +1,31 @@
+export interface ResolvedBook {
+    readonly id: number;
+    readonly name: string;
+    readonly chapterCount: number;
+}
+export interface ResolvedReference {
+    readonly book: ResolvedBook;
+    readonly startChapter: number;
+    readonly startVerse: number;
+    readonly endChapter: number;
+    readonly endVerse: number;
+    readonly startId: number;
+    readonly endId: number;
+    readonly label: string;
+}
+export interface ReferenceResolver {
+    resolveBookAlias(aliasKey: string): Promise<ResolvedBook | null>;
+    getChapterVerseCount(bookId: number, chapter: number): Promise<number | null>;
+    verseExists(bookId: number, chapter: number, verse: number): Promise<boolean>;
+}
+export type ReferenceResolutionAttempt = {
+    readonly kind: 'not-reference';
+} | {
+    readonly kind: 'invalid-reference';
+} | {
+    readonly kind: 'resolved';
+    readonly reference: ResolvedReference;
+};
+export declare function normalizeBookAlias(input: string): string;
+export declare function resolveReferenceAttempt(input: string, resolver: ReferenceResolver): Promise<ReferenceResolutionAttempt>;
+export declare function resolveReference(input: string, resolver: ReferenceResolver): Promise<ResolvedReference | null>;