@jestek-dev/scripture-engine 0.7.0 → 0.14.0

package/dist/reasons/display.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Chip display polish (0.10.0, CO-2/F22).
+ *
+ * A result's ordering is decided by applyBudgets and rank(); its CHIPS are
+ * what a person reads. These two concerns diverge at the margin: a chip whose
+ * points are real but tiny still counts toward the score, yet displaying it
+ * claims an explanatory weight the number itself denies. This module is the
+ * display seam — it never changes points, scores, or order; it only decides
+ * which chips are worth a reader's attention. Both constants are reviewed
+ * data, mirrored into `eval/budgets.json` signalBudgets for the G6
+ * reviewed-constants check.
+ */
+import type { Reason } from './types.js';
+import type { SpellingCorrection } from '../types.js';
+/**
+ * Chips display their points at one decimal. Below this value a chip prints
+ * "0.0" — asserting a contribution the display itself denies. Fixed by that
+ * display precision (0.05 is the smallest value that rounds to 0.1), not a
+ * tuning knob. Measured at introduction (84-query battery, full 25-deep
+ * windows, full reconstructed corpus): no current chip is below it — the
+ * rule is a structural guard on the display contract, not a tuned
+ * suppressor.
+ */
+export declare const CHIP_DISPLAY_MIN_POINTS = 0.05;
+/**
+ * Display floor for passage_terms chips (the homiletical-vocabulary hint).
+ *
+ * Derived from reviewed data, not tuned: the weakest evidence G5 can admit —
+ * a single term at the admission floor (`eval/budgets.json`
+ * distinctiveness.minPmi = 2.0) distilled from a one-verse note — earns
+ * 8 × log1p(1)/log1p(6) × 2/(2+6) ≈ 0.712 points, and the floor sits just
+ * beneath it. Everything that clears admission undiluted still displays;
+ * the same evidence diluted below that line (a floor-grade term inherited
+ * from a whole-chapter essay, or scaled down by the aggregate caps) is
+ * withheld as a chip while its points still count. Measured at introduction:
+ * the weakest passage_terms chip anywhere in the battery's full windows is
+ * 0.896 — nothing currently withheld; the floor exists so future admitted
+ * data cannot decorate results with sub-admission-grade chips.
+ */
+export declare const PASSAGE_TERM_CHIP_DISPLAY_FLOOR = 0.7;
+/**
+ * Withhold chips that fail the display rules. Pure and order-preserving;
+ * points, scores and result order are untouched by construction — callers
+ * apply this AFTER ranking and collapsing, to the reasons of final results.
+ *
+ * Covenant guard: explanations are part of the contract, so a result is
+ * never stripped of its last chip — when every chip fails the rules, the
+ * strongest one stays, honestly showing how little the result rests on.
+ *
+ * Returns the input array unchanged (same reference) when nothing is
+ * withheld, so untouched results stay byte-identical.
+ */
+/**
+ * The correction citation a chip label carries for one corrected token —
+ * shared between tokenEvidence's decoration and the display-level pin below,
+ * so "is this correction visibly cited?" is checked against the exact string
+ * that renders it.
+ */
+export declare function correctionCitation(typed: string): string;
+/**
+ * Guarantee every correction is VISIBLY cited on a result of a corrected
+ * query (0.12.0/QR-5 round-2, J31: "every correction shown"; covenant 5:
+ * explanations are the contract).
+ *
+ * The token-chip decoration (`Shared word: hell (corrected from "hello")`)
+ * only exists on results whose evidence includes the corrected token's
+ * token_overlap chip. Exactly the harm-class corrections tend to surface
+ * results through concept/passage evidence instead — `hello` → "hell" ranks
+ * pages of `Theme: Hell` rows with no visible trace that the query was
+ * rewritten. A citation the user cannot see is not a citation, so this pin
+ * runs LAST (after polish, like the last-chip rule) and decorates the
+ * strongest chip of any result whose displayed chips do not already carry
+ * every correction: `Theme: Hell (query corrected from "hello")`.
+ *
+ * The wording is query-level on purpose: on a mixed query ("gods forgivness")
+ * a result may rank on the UNcorrected tokens alone, so claiming the result
+ * matched via the correction would be false — what is always true, for every
+ * result of the response, is that the QUERY was corrected. Display-only by
+ * construction: points, scores, order and the page are already decided;
+ * labels change, families and points never do.
+ *
+ * Returns the input array unchanged (same reference) when every correction
+ * is already visible, so untouched results stay byte-identical.
+ */
+export declare function pinCorrectionCitations(reasons: readonly Reason[], corrections: readonly SpellingCorrection[]): readonly Reason[];
+export declare function polishChipsForDisplay(reasons: readonly Reason[]): readonly Reason[];

package/dist/reasons/display.js

@@ -0,0 +1,105 @@
+/**
+ * Chip display polish (0.10.0, CO-2/F22).
+ *
+ * A result's ordering is decided by applyBudgets and rank(); its CHIPS are
+ * what a person reads. These two concerns diverge at the margin: a chip whose
+ * points are real but tiny still counts toward the score, yet displaying it
+ * claims an explanatory weight the number itself denies. This module is the
+ * display seam — it never changes points, scores, or order; it only decides
+ * which chips are worth a reader's attention. Both constants are reviewed
+ * data, mirrored into `eval/budgets.json` signalBudgets for the G6
+ * reviewed-constants check.
+ */
+/**
+ * Chips display their points at one decimal. Below this value a chip prints
+ * "0.0" — asserting a contribution the display itself denies. Fixed by that
+ * display precision (0.05 is the smallest value that rounds to 0.1), not a
+ * tuning knob. Measured at introduction (84-query battery, full 25-deep
+ * windows, full reconstructed corpus): no current chip is below it — the
+ * rule is a structural guard on the display contract, not a tuned
+ * suppressor.
+ */
+export const CHIP_DISPLAY_MIN_POINTS = 0.05;
+/**
+ * Display floor for passage_terms chips (the homiletical-vocabulary hint).
+ *
+ * Derived from reviewed data, not tuned: the weakest evidence G5 can admit —
+ * a single term at the admission floor (`eval/budgets.json`
+ * distinctiveness.minPmi = 2.0) distilled from a one-verse note — earns
+ * 8 × log1p(1)/log1p(6) × 2/(2+6) ≈ 0.712 points, and the floor sits just
+ * beneath it. Everything that clears admission undiluted still displays;
+ * the same evidence diluted below that line (a floor-grade term inherited
+ * from a whole-chapter essay, or scaled down by the aggregate caps) is
+ * withheld as a chip while its points still count. Measured at introduction:
+ * the weakest passage_terms chip anywhere in the battery's full windows is
+ * 0.896 — nothing currently withheld; the floor exists so future admitted
+ * data cannot decorate results with sub-admission-grade chips.
+ */
+export const PASSAGE_TERM_CHIP_DISPLAY_FLOOR = 0.7;
+/**
+ * Withhold chips that fail the display rules. Pure and order-preserving;
+ * points, scores and result order are untouched by construction — callers
+ * apply this AFTER ranking and collapsing, to the reasons of final results.
+ *
+ * Covenant guard: explanations are part of the contract, so a result is
+ * never stripped of its last chip — when every chip fails the rules, the
+ * strongest one stays, honestly showing how little the result rests on.
+ *
+ * Returns the input array unchanged (same reference) when nothing is
+ * withheld, so untouched results stay byte-identical.
+ */
+/**
+ * The correction citation a chip label carries for one corrected token —
+ * shared between tokenEvidence's decoration and the display-level pin below,
+ * so "is this correction visibly cited?" is checked against the exact string
+ * that renders it.
+ */
+export function correctionCitation(typed) {
+    return `corrected from "${typed}"`;
+}
+/**
+ * Guarantee every correction is VISIBLY cited on a result of a corrected
+ * query (0.12.0/QR-5 round-2, J31: "every correction shown"; covenant 5:
+ * explanations are the contract).
+ *
+ * The token-chip decoration (`Shared word: hell (corrected from "hello")`)
+ * only exists on results whose evidence includes the corrected token's
+ * token_overlap chip. Exactly the harm-class corrections tend to surface
+ * results through concept/passage evidence instead — `hello` → "hell" ranks
+ * pages of `Theme: Hell` rows with no visible trace that the query was
+ * rewritten. A citation the user cannot see is not a citation, so this pin
+ * runs LAST (after polish, like the last-chip rule) and decorates the
+ * strongest chip of any result whose displayed chips do not already carry
+ * every correction: `Theme: Hell (query corrected from "hello")`.
+ *
+ * The wording is query-level on purpose: on a mixed query ("gods forgivness")
+ * a result may rank on the UNcorrected tokens alone, so claiming the result
+ * matched via the correction would be false — what is always true, for every
+ * result of the response, is that the QUERY was corrected. Display-only by
+ * construction: points, scores, order and the page are already decided;
+ * labels change, families and points never do.
+ *
+ * Returns the input array unchanged (same reference) when every correction
+ * is already visible, so untouched results stay byte-identical.
+ */
+export function pinCorrectionCitations(reasons, corrections) {
+    if (reasons.length === 0 || corrections.length === 0)
+        return reasons;
+    const missing = corrections.filter((correction) => !reasons.some((reason) => reason.label.includes(correctionCitation(correction.typed))));
+    if (missing.length === 0)
+        return reasons;
+    const cited = missing.map((correction) => `"${correction.typed}"`).join(', ');
+    const [strongest, ...rest] = reasons;
+    return [{ ...strongest, label: `${strongest.label} (query corrected from ${cited})` }, ...rest];
+}
+export function polishChipsForDisplay(reasons) {
+    if (reasons.length === 0)
+        return reasons;
+    const kept = reasons.filter((reason) => reason.points >= CHIP_DISPLAY_MIN_POINTS &&
+        (reason.family !== 'passage_terms' || reason.points >= PASSAGE_TERM_CHIP_DISPLAY_FLOOR));
+    if (kept.length === reasons.length)
+        return reasons;
+    // reasons arrive strongest-first from applyBudgets / the collapse merge,
+    // so [0] is the strongest chip.
+    return kept.length > 0 ? kept : [reasons[0]];
+}

package/dist/reasons/types.d.ts

@@ -16,7 +16,7 @@
  * 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 type SignalFamily = 'reference' | 'exact_phrase' | 'concept_anchor' | 'concept_lexicon' | 'token_overlap' | 'translation_variant' | 'proximity' | 'passage_terms' | 'cross_reference' | 'co_citation';
 export declare const AUTHORITATIVE_FAMILIES: readonly SignalFamily[];
 export declare function isAuthoritative(family: SignalFamily): boolean;
 /**

package/dist/reference/reference.d.ts

@@ -13,19 +13,76 @@ export interface ResolvedReference {
     readonly endId: number;
     readonly label: string;
 }
+/**
+ * One shipped book-alias row with its canonical book, for the did-you-mean
+ * (0.11.0/QR-4). Read through the port exactly once per engine instance and
+ * cached by the implementation — the engine does no I/O of its own.
+ */
+export interface BookAliasEntry {
+    readonly aliasKey: string;
+    readonly bookId: number;
+    readonly bookName: string;
+    readonly chapterCount: number;
+}
 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>;
+    /** Every shipped alias key with its canonical book — the did-you-mean vocabulary. */
+    listBookAliases(): Promise<readonly BookAliasEntry[]>;
+}
+/**
+ * A cited did-you-mean on an invalid-reference dead end (0.11.0/QR-4).
+ *
+ * Suggestion only, NEVER an auto-resolution: curated aliases (human-reviewed)
+ * auto-resolve, edit-distance matches only suggest. A machine-guessed book
+ * handing reference-level authority to the wrong passage is the one place a
+ * spelling error could do maximal theological harm, so the guess is surfaced
+ * as a question, with its edit distance as the citation. (J34/J35.)
+ */
+export interface ReferenceSuggestion {
+    /** Canonical name of the unique in-policy book match. */
+    readonly book: string;
+    /** The full suggested reference label, validated to exist in the corpus. */
+    readonly reference: string;
+    /** Integer Damerau–Levenshtein distance from the typed book text — the citation. */
+    readonly distance: number;
 }
 export type ReferenceResolutionAttempt = {
     readonly kind: 'not-reference';
 } | {
     readonly kind: 'invalid-reference';
+    /** Present when a unique in-policy near-miss book validated. See ReferenceSuggestion. */
+    readonly suggestion?: ReferenceSuggestion;
+    /**
+     * True for bare-number shapes whose book never resolved and earned no
+     * suggestion (J36): "plans 29 11" is a memory query, not a committed
+     * reference, and dead-ending it serves nobody. Explicit-separator
+     * locators (a colon or dot) state reference intent and stay
+     * invalid-reference. Callers with a discovery path honor this flag;
+     * lookups (passage(), related()) have nothing to fall through to.
+     */
+    readonly fallthroughToDiscovery: boolean;
 } | {
     readonly kind: 'resolved';
     readonly reference: ResolvedReference;
 };
+/**
+ * The ONE edit-policy table (Phase 5 design invariant), keyed by normalized
+ * key length: <5 → never suggest; 5–8 → edit distance 1; ≥9 → edit distance 2.
+ * A transposition counts as one edit (Damerau). QR-5's token correction
+ * mirrors these numbers; eval cross-checks the two stay equal. (J31/J35.)
+ */
+export declare const SUGGESTION_MIN_KEY_LENGTH = 5;
+export declare const SUGGESTION_EDIT1_MAX_KEY_LENGTH = 8;
+export declare function editDistanceBudget(keyLength: number): number;
+/**
+ * Bounded integer Damerau–Levenshtein (optimal string alignment): unit-cost
+ * insert/delete/substitute plus adjacent transposition at cost 1. Pure
+ * integer DP — no floats in decisions — and bounded: returns null when the
+ * distance exceeds `bound`, so callers never rank on an out-of-policy guess.
+ */
+export declare function damerauLevenshtein(a: string, b: string, bound: number): number | null;
 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>;

package/dist/reference/reference.js

@@ -1,6 +1,13 @@
 const COMPACT_DOT_RE = /^([1-3]?\s?[A-Za-z]+)\.(\d{1,3})\.(\d{1,3})$/;
 const BOOK_LOCATOR_RE = /^(.*?)\s*\.?\s*(\d{1,3}(?:\s*[:.]\s*\d{1,3})?(?:\s*-\s*(?:\d{1,3}\s*[:.]\s*)?\d{1,3})?)$/;
 const LOCATOR_RE = /^(\d{1,3})(?:\s*[:.]\s*(\d{1,3}))?(?:\s*-\s*(?:(\d{1,3})\s*[:.]\s*)?(\d{1,3}))?$/;
+/**
+ * The space-separated chapter/verse form (0.11.0/QR-4): "John 3 16",
+ * "1 corinthians 13 4", "John 3 1-5" — the most common phone-typed shape.
+ * The book text must end in a non-digit so an all-numeric query ("3 16")
+ * never manufactures a book candidate out of its own leading number.
+ */
+const SPACE_LOCATOR_RE = /^(.*?[^\s\d])\s+(\d{1,3})\s+(\d{1,3})(?:\s*-\s*(\d{1,3}))?$/;
 const DASH_CHARS_RE = /[‒–—―−]/g;
 const ROMAN_PREFIX_RE = /^(iii|ii|i)(?=\s|$)/;
 const ROMAN_TO_ARABIC = {
@@ -8,6 +15,52 @@ const ROMAN_TO_ARABIC = {
     ii: '2',
     iii: '3',
 };
+/**
+ * The ONE edit-policy table (Phase 5 design invariant), keyed by normalized
+ * key length: <5 → never suggest; 5–8 → edit distance 1; ≥9 → edit distance 2.
+ * A transposition counts as one edit (Damerau). QR-5's token correction
+ * mirrors these numbers; eval cross-checks the two stay equal. (J31/J35.)
+ */
+export const SUGGESTION_MIN_KEY_LENGTH = 5;
+export const SUGGESTION_EDIT1_MAX_KEY_LENGTH = 8;
+export function editDistanceBudget(keyLength) {
+    if (keyLength < SUGGESTION_MIN_KEY_LENGTH)
+        return 0;
+    return keyLength <= SUGGESTION_EDIT1_MAX_KEY_LENGTH ? 1 : 2;
+}
+/**
+ * Bounded integer Damerau–Levenshtein (optimal string alignment): unit-cost
+ * insert/delete/substitute plus adjacent transposition at cost 1. Pure
+ * integer DP — no floats in decisions — and bounded: returns null when the
+ * distance exceeds `bound`, so callers never rank on an out-of-policy guess.
+ */
+export function damerauLevenshtein(a, b, bound) {
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > bound)
+        return null;
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const d = [];
+    for (let i = 0; i < rows; i += 1) {
+        d.push(new Array(cols).fill(0));
+        d[i][0] = i;
+    }
+    for (let j = 0; j < cols; j += 1)
+        d[0][j] = j;
+    for (let i = 1; i < rows; i += 1) {
+        for (let j = 1; j < cols; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let value = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                value = Math.min(value, d[i - 2][j - 2] + 1);
+            }
+            d[i][j] = value;
+        }
+    }
+    const distance = d[a.length][b.length];
+    return distance <= bound ? distance : null;
+}
 export function normalizeBookAlias(input) {
     return input
         .trim()
@@ -15,43 +68,71 @@ export function normalizeBookAlias(input) {
         .replace(ROMAN_PREFIX_RE, (value) => ROMAN_TO_ARABIC[value])
         .replace(/[^a-z0-9]/g, '');
 }
-function parseSyntax(input) {
+function syntaxFromLocator(bookText, locator) {
+    return {
+        bookText,
+        startNumber: Number(locator[1]),
+        startVerse: locator[2] === undefined ? null : Number(locator[2]),
+        endChapter: locator[3] === undefined ? null : Number(locator[3]),
+        endNumber: locator[4] === undefined ? null : Number(locator[4]),
+    };
+}
+function parseCandidates(input) {
     const trimmed = input.trim().replace(DASH_CHARS_RE, '-');
     if (!trimmed)
         return null;
     const compact = COMPACT_DOT_RE.exec(trimmed);
     if (compact) {
         return {
-            bookText: compact[1],
-            startNumber: Number(compact[2]),
-            startVerse: Number(compact[3]),
-            endChapter: null,
-            endNumber: null,
+            candidates: [
+                {
+                    bookText: compact[1],
+                    startNumber: Number(compact[2]),
+                    startVerse: Number(compact[3]),
+                    endChapter: null,
+                    endNumber: null,
+                },
+            ],
+            explicitSeparator: true,
         };
     }
+    const candidates = [];
+    let explicitSeparator = false;
     const split = BOOK_LOCATOR_RE.exec(trimmed);
-    if (!split || !split[1]?.trim())
-        return null;
-    const locator = LOCATOR_RE.exec(split[2]);
-    if (!locator)
+    if (split && split[1]?.trim()) {
+        const locator = LOCATOR_RE.exec(split[2]);
+        if (locator) {
+            candidates.push(syntaxFromLocator(split[1], locator));
+            explicitSeparator = /[:.]/.test(split[2]);
+        }
+    }
+    const spaced = SPACE_LOCATOR_RE.exec(trimmed);
+    if (spaced) {
+        candidates.push({
+            bookText: spaced[1],
+            startNumber: Number(spaced[2]),
+            startVerse: Number(spaced[3]),
+            endChapter: null,
+            endNumber: spaced[4] === undefined ? null : Number(spaced[4]),
+        });
+    }
+    if (candidates.length === 0)
         return null;
-    return {
-        bookText: split[1],
-        startNumber: Number(locator[1]),
-        startVerse: locator[2] === undefined ? null : Number(locator[2]),
-        endChapter: locator[3] === undefined ? null : Number(locator[3]),
-        endNumber: locator[4] === undefined ? null : Number(locator[4]),
-    };
+    return { candidates, explicitSeparator };
 }
 function verseId(bookId, chapter, verse) {
     return bookId * 1_000_000 + chapter * 1_000 + verse;
 }
-function labelFor(book, startChapter, startVerse, endChapter, endVerse) {
-    if (startChapter === endChapter && startVerse === 1) {
-        return startVerse === endVerse
-            ? `${book.name} ${startChapter}:${startVerse}`
-            : `${book.name} ${startChapter}`;
-    }
+/**
+ * Renders the label — the explanation surface of a resolved reference
+ * (working agreement 5). `wholeChapter` is threaded explicitly from the parse
+ * branch that knows it (0.11.0/QR-4): until then the book-and-chapter form
+ * was keyed on "starts at verse 1", which mislabeled "John 3:1-5" as
+ * "John 3" — the right passage under the wrong name, a contract failure.
+ */
+function labelFor(book, startChapter, startVerse, endChapter, endVerse, wholeChapter) {
+    if (wholeChapter)
+        return `${book.name} ${startChapter}`;
     if (startChapter === endChapter) {
         return startVerse === endVerse
             ? `${book.name} ${startChapter}:${startVerse}`
@@ -59,20 +140,16 @@ function labelFor(book, startChapter, startVerse, endChapter, endVerse) {
     }
     return `${book.name} ${startChapter}:${startVerse}-${endChapter}:${endVerse}`;
 }
-export async function resolveReferenceAttempt(input, resolver) {
-    const syntax = parseSyntax(input);
-    if (!syntax)
-        return { kind: 'not-reference' };
-    const aliasKey = normalizeBookAlias(syntax.bookText);
-    if (!aliasKey)
-        return { kind: 'not-reference' };
-    const book = await resolver.resolveBookAlias(aliasKey);
-    if (!book)
-        return { kind: 'invalid-reference' };
+/**
+ * Resolve a parsed locator against a committed book. Null means the locator
+ * is invalid for this book (bad chapter, missing verse, inverted range).
+ */
+async function resolveWithBook(book, syntax, resolver) {
     let startChapter;
     let startVerse;
     let endChapter;
     let endVerse;
+    let wholeChapter = false;
     if (book.chapterCount === 1 && syntax.startVerse === null) {
         startChapter = 1;
         startVerse = syntax.startNumber;
@@ -81,14 +158,15 @@ export async function resolveReferenceAttempt(input, resolver) {
     }
     else if (syntax.startVerse === null) {
         if (syntax.endNumber !== null)
-            return { kind: 'invalid-reference' };
+            return null;
         startChapter = syntax.startNumber;
         startVerse = 1;
         endChapter = startChapter;
         const count = await resolver.getChapterVerseCount(book.id, startChapter);
         if (count === null)
-            return { kind: 'invalid-reference' };
+            return null;
         endVerse = count;
+        wholeChapter = true;
     }
     else {
         startChapter = syntax.startNumber;
@@ -104,26 +182,110 @@ export async function resolveReferenceAttempt(input, resolver) {
         endVerse < 1 ||
         !(await resolver.verseExists(book.id, startChapter, startVerse)) ||
         !(await resolver.verseExists(book.id, endChapter, endVerse))) {
-        return { kind: 'invalid-reference' };
+        return null;
     }
     const startId = verseId(book.id, startChapter, startVerse);
     const endId = verseId(book.id, endChapter, endVerse);
     if (endId < startId)
-        return { kind: 'invalid-reference' };
+        return null;
     return {
-        kind: 'resolved',
-        reference: {
-            book,
-            startChapter,
-            startVerse,
-            endChapter,
-            endVerse,
-            startId,
-            endId,
-            label: labelFor(book, startChapter, startVerse, endChapter, endVerse),
-        },
+        book,
+        startChapter,
+        startVerse,
+        endChapter,
+        endVerse,
+        startId,
+        endId,
+        label: labelFor(book, startChapter, startVerse, endChapter, endVerse, wholeChapter),
     };
 }
+/**
+ * The cited did-you-mean (0.11.0/QR-4), run only after every candidate's book
+ * failed to resolve. Walks the same candidates in the same order and, for the
+ * first one whose typed book text has a UNIQUE in-policy alias match whose
+ * locator validates, returns the suggestion.
+ *
+ * Determinism: the winner is the book at minimum distance; the outcome is a
+ * pure function of the typed key and the alias SET (per-book minima and a
+ * uniqueness test are row-order independent by construction — pinned by the
+ * shuffle test). A tie across books suggests nothing for that candidate: a
+ * guess between two books is exactly what this feature refuses to make.
+ */
+async function suggestForCandidates(candidates, resolver) {
+    let aliases = null;
+    for (const syntax of candidates) {
+        const typedKey = normalizeBookAlias(syntax.bookText);
+        const bound = editDistanceBudget(typedKey.length);
+        if (bound === 0)
+            continue;
+        aliases ??= await resolver.listBookAliases();
+        let min = bound + 1;
+        const bestPerBook = new Map();
+        for (const row of aliases) {
+            const distance = damerauLevenshtein(typedKey, row.aliasKey, bound);
+            if (distance === null)
+                continue;
+            const existing = bestPerBook.get(row.bookId);
+            if (!existing || distance < existing.distance) {
+                bestPerBook.set(row.bookId, {
+                    distance,
+                    name: row.bookName,
+                    chapterCount: row.chapterCount,
+                });
+            }
+            if (distance < min)
+                min = distance;
+        }
+        if (min > bound)
+            continue;
+        const winners = [...bestPerBook.entries()].filter(([, entry]) => entry.distance === min);
+        if (winners.length !== 1)
+            continue;
+        const [bookId, winner] = winners[0];
+        const book = { id: bookId, name: winner.name, chapterCount: winner.chapterCount };
+        // Validate through the exact resolution path the suggestion invites the
+        // user to take, so a suggestion never names a passage that cannot exist.
+        const reference = await resolveWithBook(book, syntax, resolver);
+        if (!reference)
+            continue;
+        return { book: book.name, reference: reference.label, distance: min };
+    }
+    return null;
+}
+export async function resolveReferenceAttempt(input, resolver) {
+    const parsed = parseCandidates(input);
+    if (!parsed)
+        return { kind: 'not-reference' };
+    // Commit rule: the FIRST candidate whose book resolves wins outright. The
+    // first candidate is the pre-0.11.0 parse, so every previously-resolving
+    // input is preserved bit-for-bit; a committed book with a bad locator is
+    // invalid-reference exactly as before, never re-parsed.
+    let sawBookText = false;
+    for (const syntax of parsed.candidates) {
+        const aliasKey = normalizeBookAlias(syntax.bookText);
+        if (!aliasKey)
+            continue;
+        sawBookText = true;
+        const book = await resolver.resolveBookAlias(aliasKey);
+        if (!book)
+            continue;
+        const reference = await resolveWithBook(book, syntax, resolver);
+        return reference
+            ? { kind: 'resolved', reference }
+            : { kind: 'invalid-reference', fallthroughToDiscovery: false };
+    }
+    if (!sawBookText)
+        return { kind: 'not-reference' };
+    // No candidate's book resolves: cite a did-you-mean if a unique in-policy
+    // match validates (J35) …
+    const suggestion = await suggestForCandidates(parsed.candidates, resolver);
+    if (suggestion) {
+        return { kind: 'invalid-reference', suggestion, fallthroughToDiscovery: false };
+    }
+    // … otherwise explicit-separator queries stay invalid-reference (committed
+    // reference intent) and bare-number shapes fall through to discovery (J36).
+    return { kind: 'invalid-reference', fallthroughToDiscovery: !parsed.explicitSeparator };
+}
 export async function resolveReference(input, resolver) {
     const attempt = await resolveReferenceAttempt(input, resolver);
     return attempt.kind === 'resolved' ? attempt.reference : null;

package/dist/tokenizer/index.d.ts

@@ -22,6 +22,41 @@ export declare function normalizeToken(raw: string): string | null;
  * set form used for overlap scoring and concept-lexicon matching.
  */
 export declare function significantWords(text: string): string[];
+/**
+ * The same significant-token set, each token paired with the SURFACE form it
+ * was normalized from — the first raw word (lowercased, punctuation-stripped)
+ * that produced it. Added for the spelling-correction citation (0.12.0/QR-5):
+ * a correction chip must cite what the user actually typed ("beleived"),
+ * never the stem the tokenizer made of it ("beleiv").
+ *
+ * This is a PAIRING, not a second tokenizer: `significantWords` delegates
+ * here, the token stream is byte-identical to what it always was (invariance-
+ * tested), and there is still no options parameter. TOKENIZER_VERSION stays
+ * 1.0.0.
+ */
+export declare function significantWordsWithSurface(text: string): {
+    token: string;
+    surface: string;
+}[];
+/**
+ * Whole-query phrase normalization for the curated alias table
+ * (0.13.0/QR-6): lowercase, apostrophes removed, punctuation folded to
+ * spaces, whitespace collapsed — and NOTHING else. Stopwords are KEPT and no
+ * stemming, archaic folding, or lemma lookup applies, because the phrases
+ * this key serves are exactly the stopword-heavy lines the token pipeline
+ * cannot represent ("it is well with my soul" -> `well soul`). Matching is
+ * whole-string EQUALITY against curated_aliases.normalized_raw, never
+ * containment, so the minimal normalization is the safety property: the less
+ * this folds, the less an alias can accidentally swallow.
+ *
+ * This is an ADDITIVE surface over the same `rawWords` core every other
+ * tokenizer output uses — not a second tokenizer, and there is still no
+ * options parameter. The token stream is untouched (invariance-tested) and
+ * TOKENIZER_VERSION stays 1.0.0. The pipeline's alias importer imports THIS
+ * function (never a mirror), so build-side keys and query-side keys cannot
+ * drift.
+ */
+export declare function normalizedPhrase(text: string): string;
 /**
  * Positional token stream: every significant occurrence, with the word index
  * it came from. Proximity scoring (intent 3) needs positions, which the