@jestek-dev/scripture-engine 0.7.1 → 0.14.0

package/dist/intents/lexical.d.ts

@@ -21,17 +21,56 @@ export declare function targetIdFor(verse: ScriptureVerse): string;
 /** Chapter-level grouping — the unit diversification thins by. */
 export declare function groupIdFor(verse: ScriptureVerse): string;
 export declare function referenceLabel(verse: ScriptureVerse): string;
+/**
+ * Significant-word count at which a verbatim phrase carries FULL exact-phrase
+ * authority (0.10.0 stage 3 taper). Below two significant words a "phrase" is
+ * one unit of meaning wearing a 60-point badge and files as token_overlap; at
+ * two it earns 2/3 authority (40 points, exactly the concept_anchor ceiling);
+ * at three or more it is a real quotation and earns the full 60.
+ *
+ * This constant is FIXED reviewed data, not a tuning knob: raising it to 4
+ * would push 2-word phrases to 30 points, colliding with weakAggregateCap 30
+ * and endangering correct remembered-phrase verbatim #1s. It is mirrored into
+ * eval/budgets.json `signalBudgets` for the G6 reviewed-constants check;
+ * changing it changes ordering, so covenant #2 requires an ENGINE_VERSION
+ * bump in the same commit.
+ */
+export declare const EXACT_PHRASE_FULL_AUTHORITY_WORDS = 3;
 /**
  * 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.
+ * Strength carries no per-verse confidence gradient: a verse either contains
+ * the phrase or it does not, and every verse containing the same phrase gets
+ * the same strength. What strength DOES encode is how much the phrase itself
+ * means — coverage of the query times the significant-width taper below.
  * 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 declare function phraseEvidence(fragment: string, fragmentWords: number, queryWords: number): Evidence;
+/**
+ * Complete-match subsumption (0.10.0 stage 3).
+ *
+ * When a candidate's evidence includes a COMPLETE whole-query exact_phrase
+ * match, its token_overlap and proximity evidence restates a fact the verbatim
+ * match already fully asserts: both are computed from the same query tokens
+ * the phrase accounts for in their entirety. Counting the restatement let a
+ * verbatim rebuke carry 11 extra points of "corroboration" that was really one
+ * fact shown three times. This is the correlation principle the budgets
+ * already commit to (G7: correlated families share one budget; identical
+ * edges collapse rather than sum), applied across the exact_phrase/
+ * token_overlap boundary — and covenant #5 improves with it, because the
+ * result no longer shows three chips asserting one fact.
+ *
+ * Fragment matches do NOT subsume: a partial quotation leaves room for the
+ * rest of the query to earn honest token credit. The caller marks only the
+ * targets whose whole-query match was emitted as exact_phrase; this function
+ * is pure and deterministic, and with an empty mark set it is the identity.
+ */
+export declare function subsumeCompletePhraseRestatements(candidates: readonly Candidate[], completePhraseTargets: ReadonlySet<string>): readonly Candidate[];
+/** A fallback phrase must carry at least two meaningful words. */
+export declare function isMeaningfulPhraseFragment(fragment: string, query: string): boolean;
 /**
  * Token-overlap and proximity evidence.
  *
@@ -40,7 +79,7 @@ export declare function phraseEvidence(fragment: string, fragmentWords: number,
  * by inverse document frequency expresses that without anyone having to
  * hand-maintain a list of which words are important.
  */
-export declare function tokenEvidence(match: TokenMatch, queryIdfTotal: number): Evidence[];
+export declare function tokenEvidence(match: TokenMatch, queryIdfTotal: number, correctionCitations?: ReadonlyMap<string, string>): Evidence[];
 /** Total IDF of the query's tokens — the denominator for coverage. */
 export declare function queryIdfTotal(tokens: readonly string[], documentFrequencies: ReadonlyMap<string, number>, documentCount: number): number;
 /** Merge per-verse evidence from every lexical intent into ranked candidates. */

package/dist/intents/lexical.js

@@ -6,6 +6,7 @@
  * 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 { correctionCitation } from '../reasons/display.js';
 import { significantWords } from '../tokenizer/index.js';
 /**
  * Canonical, sortable target id: zero-padded so lexicographic order IS
@@ -23,11 +24,28 @@ export function groupIdFor(verse) {
 export function referenceLabel(verse) {
     return `${verse.bookName} ${verse.chapter}:${verse.verse}`;
 }
+/**
+ * Significant-word count at which a verbatim phrase carries FULL exact-phrase
+ * authority (0.10.0 stage 3 taper). Below two significant words a "phrase" is
+ * one unit of meaning wearing a 60-point badge and files as token_overlap; at
+ * two it earns 2/3 authority (40 points, exactly the concept_anchor ceiling);
+ * at three or more it is a real quotation and earns the full 60.
+ *
+ * This constant is FIXED reviewed data, not a tuning knob: raising it to 4
+ * would push 2-word phrases to 30 points, colliding with weakAggregateCap 30
+ * and endangering correct remembered-phrase verbatim #1s. It is mirrored into
+ * eval/budgets.json `signalBudgets` for the G6 reviewed-constants check;
+ * changing it changes ordering, so covenant #2 requires an ENGINE_VERSION
+ * bump in the same commit.
+ */
+export const EXACT_PHRASE_FULL_AUTHORITY_WORDS = 3;
 /**
  * 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.
+ * Strength carries no per-verse confidence gradient: a verse either contains
+ * the phrase or it does not, and every verse containing the same phrase gets
+ * the same strength. What strength DOES encode is how much the phrase itself
+ * means — coverage of the query times the significant-width taper below.
  * 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,
@@ -35,17 +53,90 @@ export function referenceLabel(verse) {
  */
 export function phraseEvidence(fragment, fragmentWords, queryWords) {
     const complete = fragmentWords >= queryWords;
+    const coverage = Math.max(0, Math.min(1, fragmentWords / Math.max(1, queryWords)));
+    // Taper, part 1 (0.10.0 stage 3): a verbatim match of fewer than two
+    // significant words is one unit of meaning, not a quotation — "the cross"
+    // occurring verbatim says no more than the token `cross` matching, and the
+    // 60-point badge it used to wear is how crucifixion-mockery verses outranked
+    // the curated atonement anchors. It files under token_overlap at full
+    // strength (10 points), keeping its truthful label: the phrase genuinely
+    // occurs; the points now say how much that means.
+    if (fragmentWords < 2) {
+        return {
+            family: 'token_overlap',
+            label: complete ? 'Exact phrase' : `Contains "${fragment}"`,
+            strength: complete ? 1 : coverage,
+        };
+    }
+    // Taper, part 2: authority grows with significant width up to
+    // EXACT_PHRASE_FULL_AUTHORITY_WORDS. Two significant words earn 2/3 of the
+    // family budget (40 points — level with the concept_anchor ceiling, above
+    // weakAggregateCap 30); three or more earn the full 60.
+    const authority = Math.min(1, fragmentWords / EXACT_PHRASE_FULL_AUTHORITY_WORDS);
     return {
-        family: 'exact_phrase',
+        // Authoritative only while the verbatim text covers the MAJORITY of the
+        // query. G6's definition of the exact_phrase family is "the query text
+        // occurs verbatim in the verse" — half a query occurring verbatim is not
+        // that, it is partial lexical overlap, which is precisely what the weak
+        // tier exists to hold. Filed under token_overlap, a minority fragment
+        // keeps its honest label but competes under weak-family caps instead of
+        // outranking curated anchors.
+        family: complete || coverage >= 0.5 ? 'exact_phrase' : 'token_overlap',
         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
+        // Coverage is proportional to how much of the question this verbatim text
+        // answers. A whole-query match earns full coverage; 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))),
+        //
+        // Since 0.8.0 the caller passes SIGNIFICANT word counts, not raw ones.
+        // Raw counts let a verbatim run of function words wear authority it had
+        // not earned: "God is close to the brokenhearted" contains the fragment
+        // "is close to" — one significant word — which under raw counting scored
+        // 3/6 of full phrase authority and put Zechariah 13:7 ("the man who is
+        // close to me": strike the shepherd) above Psalm 34:18 for a grieving
+        // searcher. Coverage of MEANING, not of words, is what this signal
+        // claims to measure.
+        strength: coverage * authority,
     };
 }
+/**
+ * Complete-match subsumption (0.10.0 stage 3).
+ *
+ * When a candidate's evidence includes a COMPLETE whole-query exact_phrase
+ * match, its token_overlap and proximity evidence restates a fact the verbatim
+ * match already fully asserts: both are computed from the same query tokens
+ * the phrase accounts for in their entirety. Counting the restatement let a
+ * verbatim rebuke carry 11 extra points of "corroboration" that was really one
+ * fact shown three times. This is the correlation principle the budgets
+ * already commit to (G7: correlated families share one budget; identical
+ * edges collapse rather than sum), applied across the exact_phrase/
+ * token_overlap boundary — and covenant #5 improves with it, because the
+ * result no longer shows three chips asserting one fact.
+ *
+ * Fragment matches do NOT subsume: a partial quotation leaves room for the
+ * rest of the query to earn honest token credit. The caller marks only the
+ * targets whose whole-query match was emitted as exact_phrase; this function
+ * is pure and deterministic, and with an empty mark set it is the identity.
+ */
+export function subsumeCompletePhraseRestatements(candidates, completePhraseTargets) {
+    if (completePhraseTargets.size === 0)
+        return candidates;
+    return candidates.map((candidate) => completePhraseTargets.has(candidate.targetId)
+        ? {
+            ...candidate,
+            evidence: candidate.evidence.filter((item) => item.family !== 'token_overlap' && item.family !== 'proximity'),
+        }
+        : candidate);
+}
+/** A fallback phrase must carry at least two meaningful words. */
+export function isMeaningfulPhraseFragment(fragment, query) {
+    const querySignificant = significantWords(query);
+    if (querySignificant.length === 0) {
+        return fragment.trim().split(/\s+/).filter(Boolean).length >= 2;
+    }
+    return significantWords(fragment).length >= 2;
+}
 const PROXIMITY_WINDOW = 20;
 /**
  * Additive smoothing for the precision term. Keeps a very short verse from
@@ -60,11 +151,20 @@ const PRECISION_SMOOTHING = 2;
  * by inverse document frequency expresses that without anyone having to
  * hand-maintain a list of which words are important.
  */
-export function tokenEvidence(match, queryIdfTotal) {
+export function tokenEvidence(match, queryIdfTotal, correctionCitations) {
     const evidence = [];
     const coverage = queryIdfTotal > 0 ? Math.min(1, match.idfSum / queryIdfTotal) : 0;
     if (coverage <= 0)
         return evidence;
+    // Cited corrections (0.12.0/QR-5): a token that reached this verse only
+    // because an out-of-vocabulary typed word was corrected must SAY so, on the
+    // chip, citing the surface form the user typed — never the stem. Silence
+    // here would be a corrected query pretending to be an exact one, the
+    // theological failure mode the feature's design forbids.
+    const display = (token) => {
+        const typed = correctionCitations?.get(token);
+        return typed === undefined ? token : `${token} (${correctionCitation(typed)})`;
+    };
     // 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
@@ -84,8 +184,8 @@ export function tokenEvidence(match, queryIdfTotal) {
     evidence.push({
         family: 'token_overlap',
         label: match.matchedTokens.length === 1
-            ? `Shared word: ${match.matchedTokens[0]}`
-            : `Shared words: ${match.matchedTokens.join(', ')}`,
+            ? `Shared word: ${display(match.matchedTokens[0])}`
+            : `Shared words: ${match.matchedTokens.map(display).join(', ')}`,
         strength: coverage * precision,
     });
     // Proximity only means something with two or more matched tokens. The

package/dist/intents/spelling.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Deterministic cited spelling correction (0.12.0/QR-5) — the pure half.
+ *
+ * The pipeline precomputes a SymSpell-style delete-variant index over the
+ * artifact's whole vocabulary (corpus tokens ∪ book aliases ∪ lexicon tokens
+ * ∪ translation tokens ∪ Layer B verse terms); at query time an out-of-vocabulary token's own
+ * delete variants are looked up through the port and every candidate is
+ * verified with the bounded integer Damerau DP before one may substitute.
+ * Everything in this module is a pure function — no I/O, no floats in
+ * decisions, no locale, no randomness — so the winning correction is a
+ * function of (typed token, candidate SET) alone.
+ *
+ * ONE edit-policy table (Phase 5 design invariant): the budgets here are the
+ * SAME constants the reference did-you-mean uses (imported, not copied —
+ * there is exactly one table to review, J31/J35 review it once). The pipeline
+ * imports these same exports when it builds the delete index, and eval
+ * cross-checks that the shipped table matches a recomputation from them.
+ *
+ * Correction is a query-time-only rung: the corpus is sacred input, the query
+ * is fallible input, and only the fallible side gets the fallback. The
+ * pipeline never "corrects" scripture text, and the tokenizer is untouched
+ * (TOKENIZER_VERSION stays 1.0.0) — correction lives HERE, in the intent
+ * layer.
+ */
+/**
+ * The ONE policy table, re-exported under the spelling surface so QR-5's
+ * reviewers see the same numbers QR-4's did (J31 = J35's edit bounds):
+ * token length <5 → never correct; 5–8 → edit distance 1; ≥9 → edit
+ * distance 2; a transposition counts as 1 (Damerau).
+ *
+ * Keyed on the NORMALIZED (post-stem) token's length — the measured truth of
+ * the shipped rule, stated plainly for the J31 review (round-2 fix: earlier
+ * docs said "typed", which the code never did). It is the coherent key: the
+ * distance is computed between the normalized token and normalized dictionary
+ * terms, so budgeting by a different string's length would mix units. The
+ * practical difference is one-sided and SUPPRESSIVE — a typed word whose stem
+ * falls under 5 characters never corrects even when the surface is ≥5
+ * ("angles" stems to "angl", so angles→angels, the canonical typo, is out of
+ * policy; "sines" likewise) — i.e. strictly fewer corrections than the typed
+ * reading, never more.
+ */
+export declare const SPELLING_MIN_TOKEN_LENGTH = 5;
+export declare const SPELLING_EDIT1_MAX_TOKEN_LENGTH = 8;
+/** Edit budget for a normalized token — the same function the book did-you-mean uses. */
+export declare function spellingEditBudget(tokenLength: number): number;
+/**
+ * How many delete variants the PIPELINE must precompute for a dictionary
+ * term, derived from the typed-side policy table rather than guessed:
+ * a term of length m can be within budgeted distance of some typed token
+ * only when a typed length t exists with |t − m| ≤ budget(t), and the depth
+ * needed is the largest such budget.
+ *
+ *   budget 2 requires t ≥ 9 and |t − m| ≤ 2  → m ≥ 7
+ *   budget 1 requires 5 ≤ t ≤ 8 and |t − m| ≤ 1 → 4 ≤ m ≤ 9
+ *
+ * So: length ≥ 7 → depth 2; length 4–6 → depth 1; below 4 → 0 (no typed
+ * token in policy can ever reach it — such terms ship in spelling_terms for
+ * the vocabulary gate but contribute no delete rows). Exported for the
+ * pipeline and for the eval cross-check.
+ */
+export declare function dictionaryDeleteDepth(termLength: number): number;
+/**
+ * All strings reachable from `word` by deleting up to `depth` characters —
+ * INCLUDING the word itself (0 deletions), so a candidate reachable purely by
+ * deleting from the other side matches on the identity row. Returned sorted
+ * (code-unit order) so pipeline insertion order is byte-deterministic.
+ */
+export declare function deleteVariants(word: string, depth: number): readonly string[];
+/** One dictionary term surfaced by the delete-variant lookup. */
+export interface SpellingCandidate {
+    readonly term: string;
+    /** Corpus document frequency; 0 for vocabulary-only origins (books, lexicon, translations, verse terms). */
+    readonly documentCount: number;
+}
+export interface PickedCorrection {
+    readonly term: string;
+    /** Verified integer Damerau distance from the typed token — the citation. */
+    readonly distance: number;
+    readonly documentCount: number;
+}
+/**
+ * Chooses the winning correction for an out-of-vocabulary typed token.
+ *
+ * Every candidate is re-verified with the bounded Damerau DP (the delete
+ * index only proposes; it never decides), then the winner is selected under
+ * a TOTAL order: distance ascending → document_count descending → term
+ * lexicographic ascending. Total means row-order independent: the outcome is
+ * a pure function of the candidate SET. Distance 0 is skipped by
+ * construction — a token equal to a vocabulary term is in-vocabulary and the
+ * caller never asks about it — and an empty or fully out-of-bound candidate
+ * list yields null: no correction beats a wrong correction.
+ */
+export declare function pickCorrection(typed: string, candidates: readonly SpellingCandidate[], bound: number): PickedCorrection | null;

package/dist/intents/spelling.js

@@ -0,0 +1,124 @@
+/**
+ * Deterministic cited spelling correction (0.12.0/QR-5) — the pure half.
+ *
+ * The pipeline precomputes a SymSpell-style delete-variant index over the
+ * artifact's whole vocabulary (corpus tokens ∪ book aliases ∪ lexicon tokens
+ * ∪ translation tokens ∪ Layer B verse terms); at query time an out-of-vocabulary token's own
+ * delete variants are looked up through the port and every candidate is
+ * verified with the bounded integer Damerau DP before one may substitute.
+ * Everything in this module is a pure function — no I/O, no floats in
+ * decisions, no locale, no randomness — so the winning correction is a
+ * function of (typed token, candidate SET) alone.
+ *
+ * ONE edit-policy table (Phase 5 design invariant): the budgets here are the
+ * SAME constants the reference did-you-mean uses (imported, not copied —
+ * there is exactly one table to review, J31/J35 review it once). The pipeline
+ * imports these same exports when it builds the delete index, and eval
+ * cross-checks that the shipped table matches a recomputation from them.
+ *
+ * Correction is a query-time-only rung: the corpus is sacred input, the query
+ * is fallible input, and only the fallible side gets the fallback. The
+ * pipeline never "corrects" scripture text, and the tokenizer is untouched
+ * (TOKENIZER_VERSION stays 1.0.0) — correction lives HERE, in the intent
+ * layer.
+ */
+import { damerauLevenshtein, editDistanceBudget, SUGGESTION_EDIT1_MAX_KEY_LENGTH, SUGGESTION_MIN_KEY_LENGTH, } from '../reference/reference.js';
+/**
+ * The ONE policy table, re-exported under the spelling surface so QR-5's
+ * reviewers see the same numbers QR-4's did (J31 = J35's edit bounds):
+ * token length <5 → never correct; 5–8 → edit distance 1; ≥9 → edit
+ * distance 2; a transposition counts as 1 (Damerau).
+ *
+ * Keyed on the NORMALIZED (post-stem) token's length — the measured truth of
+ * the shipped rule, stated plainly for the J31 review (round-2 fix: earlier
+ * docs said "typed", which the code never did). It is the coherent key: the
+ * distance is computed between the normalized token and normalized dictionary
+ * terms, so budgeting by a different string's length would mix units. The
+ * practical difference is one-sided and SUPPRESSIVE — a typed word whose stem
+ * falls under 5 characters never corrects even when the surface is ≥5
+ * ("angles" stems to "angl", so angles→angels, the canonical typo, is out of
+ * policy; "sines" likewise) — i.e. strictly fewer corrections than the typed
+ * reading, never more.
+ */
+export const SPELLING_MIN_TOKEN_LENGTH = SUGGESTION_MIN_KEY_LENGTH;
+export const SPELLING_EDIT1_MAX_TOKEN_LENGTH = SUGGESTION_EDIT1_MAX_KEY_LENGTH;
+/** Edit budget for a normalized token — the same function the book did-you-mean uses. */
+export function spellingEditBudget(tokenLength) {
+    return editDistanceBudget(tokenLength);
+}
+/**
+ * How many delete variants the PIPELINE must precompute for a dictionary
+ * term, derived from the typed-side policy table rather than guessed:
+ * a term of length m can be within budgeted distance of some typed token
+ * only when a typed length t exists with |t − m| ≤ budget(t), and the depth
+ * needed is the largest such budget.
+ *
+ *   budget 2 requires t ≥ 9 and |t − m| ≤ 2  → m ≥ 7
+ *   budget 1 requires 5 ≤ t ≤ 8 and |t − m| ≤ 1 → 4 ≤ m ≤ 9
+ *
+ * So: length ≥ 7 → depth 2; length 4–6 → depth 1; below 4 → 0 (no typed
+ * token in policy can ever reach it — such terms ship in spelling_terms for
+ * the vocabulary gate but contribute no delete rows). Exported for the
+ * pipeline and for the eval cross-check.
+ */
+export function dictionaryDeleteDepth(termLength) {
+    if (termLength >= 7)
+        return 2;
+    return termLength >= 4 ? 1 : 0;
+}
+/**
+ * All strings reachable from `word` by deleting up to `depth` characters —
+ * INCLUDING the word itself (0 deletions), so a candidate reachable purely by
+ * deleting from the other side matches on the identity row. Returned sorted
+ * (code-unit order) so pipeline insertion order is byte-deterministic.
+ */
+export function deleteVariants(word, depth) {
+    const seen = new Set([word]);
+    let frontier = [word];
+    for (let round = 0; round < depth; round += 1) {
+        const next = [];
+        for (const value of frontier) {
+            if (value.length <= 1)
+                continue;
+            for (let index = 0; index < value.length; index += 1) {
+                const variant = value.slice(0, index) + value.slice(index + 1);
+                if (!seen.has(variant)) {
+                    seen.add(variant);
+                    next.push(variant);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return [...seen].sort();
+}
+/**
+ * Chooses the winning correction for an out-of-vocabulary typed token.
+ *
+ * Every candidate is re-verified with the bounded Damerau DP (the delete
+ * index only proposes; it never decides), then the winner is selected under
+ * a TOTAL order: distance ascending → document_count descending → term
+ * lexicographic ascending. Total means row-order independent: the outcome is
+ * a pure function of the candidate SET. Distance 0 is skipped by
+ * construction — a token equal to a vocabulary term is in-vocabulary and the
+ * caller never asks about it — and an empty or fully out-of-bound candidate
+ * list yields null: no correction beats a wrong correction.
+ */
+export function pickCorrection(typed, candidates, bound) {
+    if (bound <= 0)
+        return null;
+    let best = null;
+    for (const candidate of candidates) {
+        const distance = damerauLevenshtein(typed, candidate.term, bound);
+        if (distance === null || distance === 0)
+            continue;
+        if (best === null ||
+            distance < best.distance ||
+            (distance === best.distance &&
+                (candidate.documentCount > best.documentCount ||
+                    (candidate.documentCount === best.documentCount && candidate.term < best.term)))) {
+            best = { term: candidate.term, distance, documentCount: candidate.documentCount };
+        }
+    }
+    return best;
+}

package/dist/internal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * INTERNAL surface of @jestek-dev/scripture-engine (plan P7.2 / CO-5).
+ *
+ * Everything exported here is implementation detail: the repo's own pipeline,
+ * eval harness and workbench import it (one tokenizer, shared constants, the
+ * G6 reviewed-constants mirror), and it is published so those tools and
+ * white-box diagnostics can reach it — but it carries NO stability promise.
+ * Names here may move, change shape, or disappear in any version without a
+ * major bump and without a §5 consumer-contract review. Consumers pin the
+ * PUBLIC entry (`@jestek-dev/scripture-engine`): the five methods, the result
+ * types, and the `corrections`/`suggestion` fields — that surface is the
+ * contract (docs/COMPATIBILITY.md), this one is not.
+ *
+ * The internal entry is a strict superset: it re-exports the public tier too,
+ * so a tool that needs one internal symbol does not need two import
+ * specifiers. The public entry stays the compatibility boundary; the exact
+ * public surface is pinned by eval/test/public-surface.test.ts.
+ */
+export * from './index.js';
+export { collapseAnchorRuns, collapseRuns, type GroupingSpanInfo, } from './createEngine.js';
+export { CorpusRepository, MAX_CANDIDATES, MAX_PHRASE_LENGTH, type CorpusMeta, type CrossReferencePhraseRow, type CuratedAliasRow, type PericopeRow, type PhraseMatch, type TokenMatch, } from './corpus/repository.js';
+export { EXACT_PHRASE_FULL_AUTHORITY_WORDS, groupIdFor, mergeCandidates, phraseEvidence, queryIdfTotal, referenceLabel, subsumeCompletePhraseRestatements, targetIdFor, tokenEvidence, } from './intents/lexical.js';
+export { aliasConceptEvidence, aliasPassageEvidence, dedupeConceptAnchors, PASSAGE_TERM_PMI_HALF_SATURATION, sourceLabel, } from './intents/concept.js';
+export { deleteVariants, dictionaryDeleteDepth, pickCorrection, SPELLING_EDIT1_MAX_TOKEN_LENGTH, SPELLING_MIN_TOKEN_LENGTH, spellingEditBudget, type PickedCorrection, type SpellingCandidate, } from './intents/spelling.js';
+export { normalizedPhrase, normalizeToken, significantWords, significantWordsWithSurface, tokenStream, TOKENIZER_ARCHAIC_FORM_COUNT, TOKENIZER_STOPWORD_COUNT, } from './tokenizer/index.js';
+export { damerauLevenshtein, editDistanceBudget, normalizeBookAlias, resolveReference, resolveReferenceAttempt, SUGGESTION_EDIT1_MAX_KEY_LENGTH, SUGGESTION_MIN_KEY_LENGTH, type BookAliasEntry, type ReferenceResolutionAttempt, type ReferenceResolver, type ResolvedBook, type ResolvedReference, } from './reference/reference.js';
+export { makeVerseId, parseVerseId, type VerseLocation } from './reference/verseId.js';
+export { AUTHORITATIVE_FAMILIES, isAuthoritative } from './reasons/types.js';
+export { CHIP_DISPLAY_MIN_POINTS, PASSAGE_TERM_CHIP_DISPLAY_FLOOR, correctionCitation, pinCorrectionCitations, polishChipsForDisplay, } from './reasons/display.js';
+export { applyBudgets, DEFAULT_BUDGETS, type BudgetedScore, } from './ranking/budgets.js';
+export { DEFAULT_LIMIT, DEFAULT_MAX_PER_GROUP, rank, type Candidate, type RankedResult, } from './ranking/rank.js';

package/dist/internal.js

@@ -0,0 +1,31 @@
+/**
+ * INTERNAL surface of @jestek-dev/scripture-engine (plan P7.2 / CO-5).
+ *
+ * Everything exported here is implementation detail: the repo's own pipeline,
+ * eval harness and workbench import it (one tokenizer, shared constants, the
+ * G6 reviewed-constants mirror), and it is published so those tools and
+ * white-box diagnostics can reach it — but it carries NO stability promise.
+ * Names here may move, change shape, or disappear in any version without a
+ * major bump and without a §5 consumer-contract review. Consumers pin the
+ * PUBLIC entry (`@jestek-dev/scripture-engine`): the five methods, the result
+ * types, and the `corrections`/`suggestion` fields — that surface is the
+ * contract (docs/COMPATIBILITY.md), this one is not.
+ *
+ * The internal entry is a strict superset: it re-exports the public tier too,
+ * so a tool that needs one internal symbol does not need two import
+ * specifiers. The public entry stays the compatibility boundary; the exact
+ * public surface is pinned by eval/test/public-surface.test.ts.
+ */
+export * from './index.js';
+export { collapseAnchorRuns, collapseRuns, } from './createEngine.js';
+export { CorpusRepository, MAX_CANDIDATES, MAX_PHRASE_LENGTH, } from './corpus/repository.js';
+export { EXACT_PHRASE_FULL_AUTHORITY_WORDS, groupIdFor, mergeCandidates, phraseEvidence, queryIdfTotal, referenceLabel, subsumeCompletePhraseRestatements, targetIdFor, tokenEvidence, } from './intents/lexical.js';
+export { aliasConceptEvidence, aliasPassageEvidence, dedupeConceptAnchors, PASSAGE_TERM_PMI_HALF_SATURATION, sourceLabel, } from './intents/concept.js';
+export { deleteVariants, dictionaryDeleteDepth, pickCorrection, SPELLING_EDIT1_MAX_TOKEN_LENGTH, SPELLING_MIN_TOKEN_LENGTH, spellingEditBudget, } from './intents/spelling.js';
+export { normalizedPhrase, normalizeToken, significantWords, significantWordsWithSurface, tokenStream, TOKENIZER_ARCHAIC_FORM_COUNT, TOKENIZER_STOPWORD_COUNT, } from './tokenizer/index.js';
+export { damerauLevenshtein, editDistanceBudget, normalizeBookAlias, resolveReference, resolveReferenceAttempt, SUGGESTION_EDIT1_MAX_KEY_LENGTH, SUGGESTION_MIN_KEY_LENGTH, } from './reference/reference.js';
+export { makeVerseId, parseVerseId } from './reference/verseId.js';
+export { AUTHORITATIVE_FAMILIES, isAuthoritative } from './reasons/types.js';
+export { CHIP_DISPLAY_MIN_POINTS, PASSAGE_TERM_CHIP_DISPLAY_FLOOR, correctionCitation, pinCorrectionCitations, polishChipsForDisplay, } from './reasons/display.js';
+export { applyBudgets, DEFAULT_BUDGETS, } from './ranking/budgets.js';
+export { DEFAULT_LIMIT, DEFAULT_MAX_PER_GROUP, rank, } from './ranking/rank.js';

package/dist/ranking/budgets.d.ts

@@ -41,6 +41,16 @@ export interface SignalBudgets {
      * independent would inflate confidence for what is substantially one fact.
      */
     readonly correlationGroups: readonly (readonly SignalFamily[])[];
+    /**
+     * Sole-evidence floor: a ceiling applied ONLY when EVERY surviving reason's
+     * family is named in this map (when several are named, the smallest ceiling
+     * wins). A family listed here is a hint that may accompany an honest text
+     * match but must never overrule one on its own — in practice a lone
+     * translation_variant, which says "this could be the verse you mean", not
+     * "this is it". A single reason from any unlisted family disables the step,
+     * so corroborated results are untouched by construction.
+     */
+    readonly soleEvidenceMaxPoints?: Readonly<Partial<Record<SignalFamily, number>>>;
 }
 export declare const DEFAULT_BUDGETS: SignalBudgets;
 export interface BudgetedScore {
@@ -57,6 +67,8 @@ export interface BudgetedScore {
  *   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)
+ *   5. sole-evidence floor (cap the total when every surviving reason is a
+ *      hint-only family; see SignalBudgets.soleEvidenceMaxPoints)
  *
  * Scaling proportionally rather than truncating keeps the relative ordering
  * of weak reasons intact, so the displayed explanation still ranks the same

package/dist/ranking/budgets.js

@@ -26,6 +26,11 @@ export const DEFAULT_BUDGETS = {
         // Weak — individually modest, collectively capped below.
         concept_lexicon: { maxPoints: 12, maxReasons: 2 },
         token_overlap: { maxPoints: 10, maxReasons: 1 },
+        // Above token_overlap because it is not an inference: the verse genuinely
+        // reads this way somewhere. Still weak, and still inside the aggregate
+        // cap, because the match is to a bag of stems rather than to the shipped
+        // wording — it says "this could be the verse you mean", not "this is it".
+        translation_variant: { maxPoints: 14, maxReasons: 1 },
         proximity: { maxPoints: 6, maxReasons: 1 },
         passage_terms: { maxPoints: 8, maxReasons: 2 },
         cross_reference: { maxPoints: 6, maxReasons: 2 },
@@ -35,6 +40,12 @@ export const DEFAULT_BUDGETS = {
     // system, all firing at full strength, still loses to one verbatim match.
     weakAggregateCap: 30,
     correlationGroups: [['cross_reference', 'co_citation']],
+    // A lone translation_variant caps at 6 — below token_overlap's 10, level
+    // with proximity/cross_reference. Uncapped, its 14 points outranked every
+    // honest lexical signal with zero corroboration (the 2026-08-20 battery's
+    // sense-inverted harmful #1s). The value is reviewed data (J20) and is
+    // mirrored into eval/budgets.json signalBudgets for the G6 equality check.
+    soleEvidenceMaxPoints: { translation_variant: 6 },
 };
 function toReason(evidence, budget) {
     const clampedStrength = Math.min(1, Math.max(0, evidence.strength));
@@ -74,6 +85,8 @@ function compareEvidence(a, b) {
  *   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)
+ *   5. sole-evidence floor (cap the total when every surviving reason is a
+ *      hint-only family; see SignalBudgets.soleEvidenceMaxPoints)
  *
  * Scaling proportionally rather than truncating keeps the relative ordering
  * of weak reasons intact, so the displayed explanation still ranks the same
@@ -136,6 +149,32 @@ export function applyBudgets(evidence, budgets = DEFAULT_BUDGETS) {
             };
         }
     }
+    // 5: sole-evidence floor. When EVERY surviving reason's family is named in
+    // soleEvidenceMaxPoints, the whole result rests on evidence that only hints
+    // (in practice: a lone translation_variant), so its total is capped below
+    // any honest text match. Labels are untouched — the chip stays truthful;
+    // only the points now admit the evidence is a hint. One reason from any
+    // unlisted family disables the step, so corroborated results never enter it.
+    const soleCaps = budgets.soleEvidenceMaxPoints;
+    if (soleCaps && reasons.length > 0) {
+        const memberCaps = reasons.map((reason) => soleCaps[reason.family]);
+        if (memberCaps.every((cap) => cap !== undefined)) {
+            const soleCap = Math.min(...memberCaps);
+            const total = reasons.reduce((sum, reason) => sum + reason.points, 0);
+            if (total > soleCap && total > 0) {
+                capped = true;
+                const scale = soleCap / total;
+                for (let index = 0; index < reasons.length; index += 1) {
+                    const member = reasons[index];
+                    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)

package/dist/ranking/rank.js

@@ -15,9 +15,11 @@ 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.
+ * direct match outranks an equal-scoring pile of hints), then — at an exact
+ * tie between two authoritative results — curated-anchor-first, 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)
@@ -26,6 +28,21 @@ function compareResults(a, b) {
     const bAuth = b.reasons.some((reason) => isAuthoritative(reason.family));
     if (aAuth !== bAuth)
         return aAuth ? -1 : 1;
+    // Equal-score curated tie-break (0.10.0 stage 3): at an EXACT score tie
+    // between two authoritative results, the one a curated source anchors
+    // orders before one whose authority is a verbatim string hit alone. At
+    // identical evidence weight, preferring the passage a named human recorded
+    // for this concept over "the string occurs" is the product's stated reason
+    // to exist — and it adjudicates no theology: it prefers recorded human
+    // curation, not a doctrine. It fires ONLY on exact ties between
+    // authoritative results; unequal scores are never reordered, and the
+    // comparator remains a total order.
+    if (aAuth && bAuth) {
+        const aAnchor = a.reasons.some((reason) => reason.family === 'concept_anchor');
+        const bAnchor = b.reasons.some((reason) => reason.family === 'concept_anchor');
+        if (aAnchor !== bAnchor)
+            return aAnchor ? -1 : 1;
+    }
     return a.targetId < b.targetId ? -1 : a.targetId > b.targetId ? 1 : 0;
 }
 export function rank(candidates, options = {}) {