@jestek-dev/scripture-engine 0.7.0

package/dist/createEngine.js

@@ -0,0 +1,338 @@
+/**
+ * The orchestrator — the only place in the engine that does I/O, and it does
+ * it through `ContentQueryPort` alone.
+ *
+ * Intent order follows the 2026-07-20 plan exactly:
+ *   1. explicit reference lookup
+ *   2. exact normalized phrase
+ *   3. distinctive tokens with proximity preference
+ *   4. conservative normalization (inflection + archaic forms)
+ * Curated expansion (concepts, cross-references) attaches at step 5 in Phase
+ * 2 without changing anything above it.
+ */
+import { ConceptRepository, CorpusRepository, searchLongestFragment, } from './corpus/repository.js';
+import { ENGINE_VERSION, TOKENIZER_VERSION } from './config/engineVersion.js';
+import { mergeCandidates, phraseEvidence, queryIdfTotal, referenceLabel, significantWords, targetIdFor, tokenEvidence, } from './intents/lexical.js';
+import { conceptAnchorEvidence, crossReferenceEvidence, passageTermEvidence, relatedConceptEvidence, } from './intents/concept.js';
+import { rank } from './ranking/rank.js';
+const SUPPORTED_SCHEMA_VERSIONS = new Set(['1', '2', '3', '4', '5']);
+/**
+ * Lyric tokens admitted to forSong(). A full lyric sheet is hundreds of
+ * mostly-common words; past this point they add candidates without adding
+ * evidence, and drown the themes the writer actually stated.
+ */
+const MAX_LYRIC_TOKENS = 40;
+export async function createEngine(database, options = {}) {
+    const repository = new CorpusRepository(database);
+    const meta = await repository.readMeta();
+    if (!SUPPORTED_SCHEMA_VERSIONS.has(meta.schemaVersion)) {
+        throw new Error(`createEngine: artifact schema v${meta.schemaVersion} is not supported by ` +
+            `engine ${ENGINE_VERSION} (supports v${[...SUPPORTED_SCHEMA_VERSIONS].join(', v')})`);
+    }
+    if ((options.enforceTokenizerVersion ?? true) && meta.tokenizerVersion !== TOKENIZER_VERSION) {
+        throw new Error(`createEngine: artifact was tokenized by tokenizer ${meta.tokenizerVersion} but this ` +
+            `engine uses ${TOKENIZER_VERSION}. Precomputed token postings would describe a ` +
+            `vocabulary this runtime cannot reproduce. Rebuild the artifact.`);
+    }
+    // The concept layer is optional: a v1 artifact has no concept tables, and
+    // the engine still works as a lexical search rather than refusing to open.
+    const conceptRepository = new ConceptRepository(database);
+    const concepts = (await conceptRepository.hasConceptLayer()) ? conceptRepository : null;
+    const hasPassageTerms = await conceptRepository.hasPassageTerms();
+    const documentCount = await repository.documentCount();
+    const identity = {
+        engineVersion: ENGINE_VERSION,
+        corpusFingerprint: meta.corpusFingerprint,
+        layerFingerprint: meta.layerFingerprint,
+    };
+    async function discover(query) {
+        const verses = new Map();
+        const contributions = [];
+        // Step 2 — verbatim text. Tries the whole query first and falls back to
+        // its longest matching fragment, so a paraphrase still gets credit for
+        // the part the user quoted exactly. Only for multi-word queries: a single
+        // word "matching a phrase" is the token intent wearing an authoritative
+        // badge it has not earned.
+        if (query.trim().includes(' ')) {
+            const whole = await repository.searchPhrase(query);
+            const queryWords = query.trim().split(/\s+/).filter(Boolean).length;
+            if (whole.length > 0) {
+                for (const match of whole) {
+                    verses.set(targetIdFor(match), match);
+                    contributions.push({
+                        verse: match,
+                        evidence: [phraseEvidence(query.trim(), queryWords, queryWords)],
+                    });
+                }
+            }
+            else {
+                const fragment = await searchLongestFragment(repository, query);
+                if (fragment) {
+                    for (const match of fragment.matches) {
+                        verses.set(targetIdFor(match), match);
+                        contributions.push({
+                            verse: match,
+                            evidence: [
+                                phraseEvidence(fragment.fragment, fragment.fragmentWords, fragment.queryWords),
+                            ],
+                        });
+                    }
+                }
+            }
+        }
+        // Steps 3-4 — tokens with proximity. Normalization is inherent: the
+        // shared tokenizer folds inflection and archaic forms on both sides.
+        const tokens = significantWords(query);
+        if (tokens.length > 0) {
+            const frequencies = await repository.tokenDocumentCounts(tokens);
+            const idfTotal = queryIdfTotal(tokens, frequencies, documentCount);
+            for (const match of await repository.searchTokens(tokens, documentCount)) {
+                verses.set(targetIdFor(match), match);
+                contributions.push({ verse: match, evidence: tokenEvidence(match, idfTotal) });
+            }
+        }
+        // Step 5a — homiletical vocabulary. Weak by design and weak by budget.
+        if (hasPassageTerms && tokens.length > 0) {
+            for (const match of await conceptRepository.searchPassageTerms(tokens)) {
+                verses.set(targetIdFor(match), match);
+                contributions.push({ verse: match, evidence: [passageTermEvidence(match)] });
+            }
+        }
+        // Step 5 — curated concept expansion. This is the step that can find a
+        // passage sharing NO vocabulary with the query, because a human recorded
+        // that it belongs. Everything above it is untouched by its presence.
+        if (concepts && tokens.length > 0) {
+            const matched = await concepts.matchConcepts(tokens);
+            if (matched.length > 0) {
+                const specificity = new Map(matched.map((match) => [match.conceptId, match.matchedTokenCount]));
+                const anchors = await concepts.anchorVerses(matched.map((match) => match.conceptId));
+                for (const anchor of anchors) {
+                    verses.set(targetIdFor(anchor), anchor);
+                    contributions.push({
+                        verse: anchor,
+                        evidence: [
+                            conceptAnchorEvidence(anchor, specificity.get(anchor.conceptId) ?? 1),
+                        ],
+                    });
+                }
+                // One hop through the curated graph, filed as weak evidence.
+                const relatedIds = await concepts.relatedConcepts(matched.map((match) => match.conceptId));
+                for (const anchor of await concepts.anchorVerses(relatedIds)) {
+                    verses.set(targetIdFor(anchor), anchor);
+                    contributions.push({ verse: anchor, evidence: [relatedConceptEvidence(anchor)] });
+                }
+                // Cross-reference expansion seeded ONLY from concept anchors, never
+                // from arbitrary lexical hits. Seeding from weak matches is how a
+                // curated graph turns into a random walk.
+                const seeds = [...new Set(anchors.map((anchor) => anchor.verseId))].sort((a, b) => a - b);
+                const seedLabels = new Map(anchors.map((anchor) => [anchor.verseId, referenceLabel(anchor)]));
+                const maxVotes = await concepts.maxCrossReferenceVotes();
+                for (const edge of await concepts.expandCrossReferences(seeds)) {
+                    verses.set(targetIdFor(edge), edge);
+                    contributions.push({
+                        verse: edge,
+                        evidence: [
+                            crossReferenceEvidence(edge, maxVotes, seedLabels.get(edge.fromVerseId) ?? 'a matched passage'),
+                        ],
+                    });
+                }
+            }
+        }
+        const ranked = rank(mergeCandidates(contributions), options.rankOptions);
+        return ranked.map((result) => {
+            const verse = verses.get(result.targetId);
+            return {
+                targetId: result.targetId,
+                reference: referenceLabel(verse),
+                excerpt: verse.text,
+                score: result.score,
+                reasons: result.reasons,
+            };
+        });
+    }
+    async function relatedFor(reference) {
+        const trimmed = reference.trim();
+        const attempt = await repository.resolveReference(trimmed);
+        if (attempt.kind !== 'resolved') {
+            return { kind: 'invalid-reference', query: trimmed, ...identity };
+        }
+        const resolved = attempt.reference;
+        if (!concepts) {
+            return { kind: 'related', reference: resolved.label, concepts: [], results: [], ...identity };
+        }
+        const anchoring = await concepts.conceptsAnchoring(resolved.startId, resolved.endId);
+        // Populate each concept's full anchor list, exactly as themes() does.
+        // A consumer showing "this passage belongs to Refuge in trouble" wants
+        // the rest of that concept's passages as the obvious next click, and an
+        // empty array here reads as "this concept anchors nothing" rather than
+        // as data we declined to fetch.
+        const anchorsByConcept = new Map();
+        for (const anchor of await concepts.anchorVerses(anchoring.map((concept) => concept.conceptId))) {
+            const bucket = anchorsByConcept.get(anchor.conceptId);
+            const label = referenceLabel(anchor);
+            if (bucket) {
+                if (!bucket.includes(label))
+                    bucket.push(label);
+            }
+            else {
+                anchorsByConcept.set(anchor.conceptId, [label]);
+            }
+        }
+        // Seed cross-reference expansion from the verses the user actually
+        // named. Unlike discovery, there is no query to be wrong about: the
+        // passage IS the input, so its edges are exactly what was asked for.
+        const seeds = [];
+        for (let verseId = resolved.startId; verseId <= resolved.endId; verseId += 1) {
+            seeds.push(verseId);
+        }
+        const maxVotes = await concepts.maxCrossReferenceVotes();
+        const verses = new Map();
+        const contributions = [];
+        for (const edge of await concepts.expandCrossReferences(seeds)) {
+            // A passage is not related to itself.
+            if (edge.verseId >= resolved.startId && edge.verseId <= resolved.endId)
+                continue;
+            verses.set(targetIdFor(edge), edge);
+            contributions.push({
+                verse: edge,
+                evidence: [crossReferenceEvidence(edge, maxVotes, resolved.label)],
+            });
+        }
+        const ranked = rank(mergeCandidates(contributions), options.rankOptions);
+        return {
+            kind: 'related',
+            reference: resolved.label,
+            concepts: anchoring.map((concept) => ({
+                conceptId: concept.conceptId,
+                label: concept.label,
+                matchedOn: resolved.label,
+                anchors: anchorsByConcept.get(concept.conceptId) ?? [],
+            })),
+            results: ranked.map((result) => {
+                const verse = verses.get(result.targetId);
+                return {
+                    targetId: result.targetId,
+                    reference: referenceLabel(verse),
+                    excerpt: verse.text,
+                    score: result.score,
+                    reasons: result.reasons,
+                };
+            }),
+            ...identity,
+        };
+    }
+    return {
+        engineVersion: ENGINE_VERSION,
+        corpusFingerprint: meta.corpusFingerprint,
+        layerFingerprint: meta.layerFingerprint,
+        async research(query) {
+            const trimmed = query.trim();
+            // Step 1 — an explicit reference wins outright and short-circuits.
+            // Discovery never runs for "Ps 46": the user asked for a passage, not
+            // for verses that resemble the string "Ps 46".
+            const attempt = await repository.resolveReference(trimmed);
+            if (attempt.kind === 'resolved') {
+                return {
+                    kind: 'reference',
+                    passage: await repository.loadPassage(attempt.reference),
+                    ...identity,
+                };
+            }
+            if (attempt.kind === 'invalid-reference') {
+                return { kind: 'invalid-reference', query: trimmed, ...identity };
+            }
+            return { kind: 'discovery', query: trimmed, results: await discover(trimmed), ...identity };
+        },
+        async themes(query) {
+            if (!concepts)
+                return [];
+            const tokens = significantWords(query);
+            if (tokens.length === 0)
+                return [];
+            const matched = await concepts.matchConcepts(tokens);
+            if (matched.length === 0)
+                return [];
+            // One anchor query for all matched concepts rather than one per concept:
+            // the cost is the same and the ordering is stable.
+            const anchors = await concepts.anchorVerses(matched.map((match) => match.conceptId));
+            const byConcept = new Map();
+            for (const anchor of anchors) {
+                const bucket = byConcept.get(anchor.conceptId);
+                const label = referenceLabel(anchor);
+                if (bucket) {
+                    if (!bucket.includes(label))
+                        bucket.push(label);
+                }
+                else {
+                    byConcept.set(anchor.conceptId, [label]);
+                }
+            }
+            // Most specific first — a three-word lexicon hit says more about intent
+            // than a one-word one — then by id, so ties never depend on row order.
+            return [...matched]
+                .sort((a, b) => b.matchedTokenCount !== a.matchedTokenCount
+                ? b.matchedTokenCount - a.matchedTokenCount
+                : a.conceptId < b.conceptId
+                    ? -1
+                    : 1)
+                .map((match) => ({
+                conceptId: match.conceptId,
+                label: match.label,
+                matchedOn: match.matchedPhrase,
+                anchors: byConcept.get(match.conceptId) ?? [],
+            }));
+        },
+        async passage(reference) {
+            const trimmed = reference.trim();
+            const attempt = await repository.resolveReference(trimmed);
+            if (attempt.kind === 'resolved') {
+                return {
+                    kind: 'passage',
+                    passage: await repository.loadPassage(attempt.reference),
+                    ...identity,
+                };
+            }
+            return { kind: 'invalid-reference', query: trimmed, ...identity };
+        },
+        related: relatedFor,
+        async forSong(input) {
+            // Fields are concatenated in a FIXED order, most-intentional first, and
+            // lyrics are truncated. Both choices are about determinism and noise
+            // rather than taste: field order must not depend on object key order,
+            // and a full lyric sheet contributes hundreds of low-IDF tokens that
+            // would swamp a stated theme without adding evidence.
+            const parts = [];
+            if (input.themes?.length)
+                parts.push(input.themes.join(' '));
+            if (input.title)
+                parts.push(input.title);
+            if (input.lyrics)
+                parts.push(significantWords(input.lyrics).slice(0, MAX_LYRIC_TOKENS).join(' '));
+            const query = parts.join(' ').trim();
+            const results = query === '' ? [] : await discover(query);
+            // A foundational reference is a claim the writer made about the song, so
+            // its curated edges are admitted alongside discovery — but never as the
+            // only input, and never seeded from lyrics, which are not a claim.
+            if (input.foundationalRef && concepts) {
+                const attempt = await repository.resolveReference(input.foundationalRef);
+                if (attempt.kind === 'resolved') {
+                    const related = await relatedFor(input.foundationalRef);
+                    if (related.kind === 'related') {
+                        const seen = new Set(results.map((result) => result.targetId));
+                        const merged = [...results];
+                        for (const extra of related.results) {
+                            if (!seen.has(extra.targetId))
+                                merged.push(extra);
+                        }
+                        merged.sort((a, b) => (b.score !== a.score ? b.score - a.score : a.targetId < b.targetId ? -1 : 1));
+                        return { kind: 'discovery', query, results: merged, ...identity };
+                    }
+                }
+            }
+            return { kind: 'discovery', query, results, ...identity };
+        },
+        async close() {
+            await repository.close();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public API for @jestek-dev/scripture-engine.
+ *
+ * Phase 0 exports the pure core that later phases build on: the shared
+ * tokenizer, the reference parser, the typed reason vocabulary, the signal
+ * budgets, and the deterministic ranker. The intent ladder (Phase 1) and the
+ * concept layer (Phase 2) attach to these without changing their contracts.
+ */
+export { ENGINE_VERSION, TOKENIZER_VERSION } from './config/engineVersion.js';
+export { createEngine, type EngineOptions, type ScriptureEngine } from './createEngine.js';
+export { CorpusRepository, MAX_CANDIDATES, MAX_PHRASE_LENGTH, type CorpusMeta, type PhraseMatch, type TokenMatch, } from './corpus/repository.js';
+export { groupIdFor, mergeCandidates, phraseEvidence, queryIdfTotal, referenceLabel, targetIdFor, tokenEvidence, } from './intents/lexical.js';
+export { normalizeToken, significantWords, tokenStream, TOKENIZER_ARCHAIC_FORM_COUNT, TOKENIZER_STOPWORD_COUNT, } from './tokenizer/index.js';
+export { normalizeBookAlias, resolveReference, resolveReferenceAttempt, 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, type Evidence, type Provenance, type Reason, type SignalFamily, } from './reasons/types.js';
+export { applyBudgets, DEFAULT_BUDGETS, type BudgetedScore, type FamilyBudget, type SignalBudgets, } from './ranking/budgets.js';
+export { DEFAULT_LIMIT, DEFAULT_MAX_PER_GROUP, rank, type Candidate, type RankedResult, type RankOptions, } from './ranking/rank.js';
+export type { ConceptMatch, PassageResult, RelatedResult, SongInput, ContentQueryPort, ContentQueryResult, ContentScalar, DiscoveryResult, ResearchOutcome, ResearchResult, ResultIdentity, ScripturePassage, ScriptureVerse, } from './types.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * Public API for @jestek-dev/scripture-engine.
+ *
+ * Phase 0 exports the pure core that later phases build on: the shared
+ * tokenizer, the reference parser, the typed reason vocabulary, the signal
+ * budgets, and the deterministic ranker. The intent ladder (Phase 1) and the
+ * concept layer (Phase 2) attach to these without changing their contracts.
+ */
+export { ENGINE_VERSION, TOKENIZER_VERSION } from './config/engineVersion.js';
+export { createEngine } from './createEngine.js';
+export { CorpusRepository, MAX_CANDIDATES, MAX_PHRASE_LENGTH, } from './corpus/repository.js';
+export { groupIdFor, mergeCandidates, phraseEvidence, queryIdfTotal, referenceLabel, targetIdFor, tokenEvidence, } from './intents/lexical.js';
+export { normalizeToken, significantWords, tokenStream, TOKENIZER_ARCHAIC_FORM_COUNT, TOKENIZER_STOPWORD_COUNT, } from './tokenizer/index.js';
+export { normalizeBookAlias, resolveReference, resolveReferenceAttempt, } from './reference/reference.js';
+export { makeVerseId, parseVerseId } from './reference/verseId.js';
+export { AUTHORITATIVE_FAMILIES, isAuthoritative, } from './reasons/types.js';
+export { applyBudgets, DEFAULT_BUDGETS, } from './ranking/budgets.js';
+export { DEFAULT_LIMIT, DEFAULT_MAX_PER_GROUP, rank, } from './ranking/rank.js';

package/dist/intents/concept.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Concept intent — step 5 of the ladder, and the reason this engine exists.
+ *
+ * The lexical intents can only find verses that share vocabulary with the
+ * query. This one finds verses that share MEANING, because a human wrote
+ * down that they do and said on what authority.
+ *
+ * Note what it does NOT do: it renders no theological judgment. It reports
+ * that a named source associates this passage with this concept, and names
+ * the source. Where that source is us, the chip says "LH editorial" and the
+ * reader can weigh it accordingly.
+ */
+import type { ConceptAnchorRow, CrossReferenceRow } from '../corpus/repository.js';
+import type { Evidence } from '../reasons/types.js';
+/**
+ * Anchor evidence.
+ *
+ * Strength is the curated weight, which is a PRIOR: editorial confidence for
+ * hand-authored anchors, normalized vote share for OpenBible ones. It is
+ * never treated as a probability of correctness, and it enters the ranker
+ * under the concept_anchor budget like any other bounded input.
+ *
+ * `specificity` scales strength by how much of the concept's lexicon phrase
+ * the query actually matched. A one-token match ("grace") is real but thin
+ * evidence that the user meant the curated concept; a four-token match
+ * ("be doers of the word") is close to unambiguous.
+ */
+export declare function conceptAnchorEvidence(anchor: ConceptAnchorRow, matchedTokenCount: number): Evidence;
+/**
+ * Evidence for a concept reached one hop away in the curated graph.
+ *
+ * Deliberately filed under the WEAK `concept_lexicon` family rather than
+ * `concept_anchor`: "related to something you asked about" is a genuinely
+ * weaker claim than "this is what you asked about", and the budget system
+ * only protects us if evidence is filed honestly.
+ */
+export declare function relatedConceptEvidence(anchor: ConceptAnchorRow): Evidence;
+/**
+ * Cross-reference evidence.
+ *
+ * Votes are normalized against the corpus maximum on a log scale: the
+ * difference between 3 votes and 30 is meaningful, between 300 and 330 is
+ * not, and a linear scale would let a handful of famous verse pairs
+ * monopolize the signal.
+ */
+export declare function crossReferenceEvidence(edge: CrossReferenceRow, maxVotes: number, fromReference: string): Evidence;
+/**
+ * Homiletical term-profile evidence (Layer B).
+ *
+ * Strength saturates: matching three distinctive terms is meaningfully more
+ * than one, but twenty is not meaningfully more than ten, and a linear scale
+ * would let one verbose exposition dominate. Log growth also keeps the signal
+ * honest about what it is — a hint that people preaching this passage reach
+ * for these words, nothing stronger.
+ */
+export declare function passageTermEvidence(match: {
+    matchedTerms: readonly string[];
+    pmiSum: number;
+    sourceIds: string;
+    minSpanVerses: number;
+    locator: string;
+}): Evidence;
+/**
+ * Human-facing source names. Kept here rather than read from the artifact
+ * because these strings appear in result chips, and a chip that says
+ * "openbible-topics" leaks a database identifier into the product.
+ */
+declare function sourceLabel(sourceId: string): string;
+export { sourceLabel };

package/dist/intents/concept.js

@@ -0,0 +1,143 @@
+/**
+ * Concept intent — step 5 of the ladder, and the reason this engine exists.
+ *
+ * The lexical intents can only find verses that share vocabulary with the
+ * query. This one finds verses that share MEANING, because a human wrote
+ * down that they do and said on what authority.
+ *
+ * Note what it does NOT do: it renders no theological judgment. It reports
+ * that a named source associates this passage with this concept, and names
+ * the source. Where that source is us, the chip says "LH editorial" and the
+ * reader can weigh it accordingly.
+ */
+/**
+ * Anchor evidence.
+ *
+ * Strength is the curated weight, which is a PRIOR: editorial confidence for
+ * hand-authored anchors, normalized vote share for OpenBible ones. It is
+ * never treated as a probability of correctness, and it enters the ranker
+ * under the concept_anchor budget like any other bounded input.
+ *
+ * `specificity` scales strength by how much of the concept's lexicon phrase
+ * the query actually matched. A one-token match ("grace") is real but thin
+ * evidence that the user meant the curated concept; a four-token match
+ * ("be doers of the word") is close to unambiguous.
+ */
+export function conceptAnchorEvidence(anchor, matchedTokenCount) {
+    const specificity = Math.min(1, 0.55 + 0.15 * Math.max(0, matchedTokenCount - 1));
+    return {
+        family: 'concept_anchor',
+        label: `Theme: ${anchor.conceptLabel}`,
+        strength: Math.max(0, Math.min(1, anchor.weight)) * specificity,
+        provenance: {
+            sourceId: anchor.sourceId,
+            label: sourceLabel(anchor.sourceId),
+            ...(anchor.locator ? { locator: anchor.locator } : {}),
+            weight: anchor.weight,
+        },
+    };
+}
+/**
+ * Evidence for a concept reached one hop away in the curated graph.
+ *
+ * Deliberately filed under the WEAK `concept_lexicon` family rather than
+ * `concept_anchor`: "related to something you asked about" is a genuinely
+ * weaker claim than "this is what you asked about", and the budget system
+ * only protects us if evidence is filed honestly.
+ */
+export function relatedConceptEvidence(anchor) {
+    return {
+        family: 'concept_lexicon',
+        label: `Related theme: ${anchor.conceptLabel}`,
+        strength: Math.max(0, Math.min(1, anchor.weight)) * 0.5,
+        provenance: {
+            sourceId: anchor.sourceId,
+            label: sourceLabel(anchor.sourceId),
+            ...(anchor.locator ? { locator: anchor.locator } : {}),
+        },
+    };
+}
+/**
+ * Cross-reference evidence.
+ *
+ * Votes are normalized against the corpus maximum on a log scale: the
+ * difference between 3 votes and 30 is meaningful, between 300 and 330 is
+ * not, and a linear scale would let a handful of famous verse pairs
+ * monopolize the signal.
+ */
+export function crossReferenceEvidence(edge, maxVotes, fromReference) {
+    const normalized = maxVotes > 1 ? Math.log1p(Math.max(0, edge.votes)) / Math.log1p(maxVotes) : 0;
+    return {
+        family: 'cross_reference',
+        label: `Cross-referenced from ${fromReference}`,
+        strength: Math.max(0, Math.min(1, normalized)),
+        provenance: {
+            sourceId: edge.sourceId,
+            label: sourceLabel(edge.sourceId),
+            locator: fromReference,
+            weight: edge.votes,
+        },
+    };
+}
+/**
+ * Homiletical term-profile evidence (Layer B).
+ *
+ * Strength saturates: matching three distinctive terms is meaningfully more
+ * than one, but twenty is not meaningfully more than ten, and a linear scale
+ * would let one verbose exposition dominate. Log growth also keeps the signal
+ * honest about what it is — a hint that people preaching this passage reach
+ * for these words, nothing stronger.
+ */
+export function passageTermEvidence(match) {
+    const saturating = Math.log1p(match.matchedTerms.length) / Math.log1p(6);
+    // Specificity: evidence distilled from a one-verse note is a stronger claim
+    // about THIS verse than the same words inherited from a whole-psalm essay.
+    // 1 verse -> 1.0, 6 verses -> ~0.61, a whole chapter -> ~0.45. Gentle on
+    // purpose: diffuse commentary is discounted, never discarded.
+    const span = Math.max(1, match.minSpanVerses);
+    const specificity = 1 / (1 + 0.25 * Math.log2(span));
+    return {
+        family: 'passage_terms',
+        label: match.matchedTerms.length === 1
+            ? `Preached vocabulary: ${match.matchedTerms[0]}`
+            : `Preached vocabulary: ${match.matchedTerms.slice(0, 3).join(', ')}`,
+        strength: Math.max(0, Math.min(1, saturating * specificity)),
+        provenance: {
+            sourceId: match.sourceIds,
+            label: joinedSourceLabel(match.sourceIds),
+            locator: match.locator,
+        },
+    };
+}
+/** '+'-joined source ids rendered as human labels. */
+function joinedSourceLabel(sourceIds) {
+    return sourceIds
+        .split('+')
+        .map((id) => sourceLabel(id))
+        .join(' + ');
+}
+/**
+ * Human-facing source names. Kept here rather than read from the artifact
+ * because these strings appear in result chips, and a chip that says
+ * "openbible-topics" leaks a database identifier into the product.
+ */
+function sourceLabel(sourceId) {
+    switch (sourceId) {
+        case 'editorial':
+            return 'LH editorial';
+        case 'openbible-topics':
+            return 'OpenBible topical votes (CC BY)';
+        case 'openbible-xrefs':
+            return 'OpenBible cross-references (CC BY)';
+        case 'maclaren-psalms':
+            return 'Maclaren, Expositions (public domain)';
+        case 'treasury-of-david-01':
+        case 'treasury-of-david-02':
+        case 'treasury-of-david-04':
+        case 'treasury-of-david-06':
+            return 'Spurgeon, Treasury of David (public domain)';
+        default:
+            return sourceId;
+    }
+}
+export { sourceLabel };

package/dist/intents/lexical.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 type { Candidate } from '../ranking/rank.js';
+import type { Evidence } from '../reasons/types.js';
+import { significantWords } from '../tokenizer/index.js';
+import type { TokenMatch } from '../corpus/repository.js';
+import type { ScriptureVerse } from '../types.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 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;
+/**
+ * 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 declare function phraseEvidence(fragment: string, fragmentWords: number, queryWords: number): Evidence;
+/**
+ * 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 declare function tokenEvidence(match: TokenMatch, queryIdfTotal: number): 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. */
+export declare function mergeCandidates(contributions: readonly {
+    verse: ScriptureVerse;
+    evidence: readonly Evidence[];
+}[]): Candidate[];
+export { significantWords };