@jestek-dev/scripture-engine 0.7.0

package/dist/reference/reference.js

@@ -0,0 +1,130 @@
+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}))?$/;
+const DASH_CHARS_RE = /[‒–—―−]/g;
+const ROMAN_PREFIX_RE = /^(iii|ii|i)(?=\s|$)/;
+const ROMAN_TO_ARABIC = {
+    i: '1',
+    ii: '2',
+    iii: '3',
+};
+export function normalizeBookAlias(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(ROMAN_PREFIX_RE, (value) => ROMAN_TO_ARABIC[value])
+        .replace(/[^a-z0-9]/g, '');
+}
+function parseSyntax(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,
+        };
+    }
+    const split = BOOK_LOCATOR_RE.exec(trimmed);
+    if (!split || !split[1]?.trim())
+        return null;
+    const locator = LOCATOR_RE.exec(split[2]);
+    if (!locator)
+        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]),
+    };
+}
+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}`;
+    }
+    if (startChapter === endChapter) {
+        return startVerse === endVerse
+            ? `${book.name} ${startChapter}:${startVerse}`
+            : `${book.name} ${startChapter}:${startVerse}-${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' };
+    let startChapter;
+    let startVerse;
+    let endChapter;
+    let endVerse;
+    if (book.chapterCount === 1 && syntax.startVerse === null) {
+        startChapter = 1;
+        startVerse = syntax.startNumber;
+        endChapter = 1;
+        endVerse = syntax.endNumber ?? syntax.startNumber;
+    }
+    else if (syntax.startVerse === null) {
+        if (syntax.endNumber !== null)
+            return { kind: 'invalid-reference' };
+        startChapter = syntax.startNumber;
+        startVerse = 1;
+        endChapter = startChapter;
+        const count = await resolver.getChapterVerseCount(book.id, startChapter);
+        if (count === null)
+            return { kind: 'invalid-reference' };
+        endVerse = count;
+    }
+    else {
+        startChapter = syntax.startNumber;
+        startVerse = syntax.startVerse;
+        endChapter = syntax.endChapter ?? startChapter;
+        endVerse = syntax.endNumber ?? startVerse;
+    }
+    if (startChapter < 1 ||
+        endChapter < 1 ||
+        startChapter > book.chapterCount ||
+        endChapter > book.chapterCount ||
+        startVerse < 1 ||
+        endVerse < 1 ||
+        !(await resolver.verseExists(book.id, startChapter, startVerse)) ||
+        !(await resolver.verseExists(book.id, endChapter, endVerse))) {
+        return { kind: 'invalid-reference' };
+    }
+    const startId = verseId(book.id, startChapter, startVerse);
+    const endId = verseId(book.id, endChapter, endVerse);
+    if (endId < startId)
+        return { kind: 'invalid-reference' };
+    return {
+        kind: 'resolved',
+        reference: {
+            book,
+            startChapter,
+            startVerse,
+            endChapter,
+            endVerse,
+            startId,
+            endId,
+            label: labelFor(book, startChapter, startVerse, endChapter, endVerse),
+        },
+    };
+}
+export async function resolveReference(input, resolver) {
+    const attempt = await resolveReferenceAttempt(input, resolver);
+    return attempt.kind === 'resolved' ? attempt.reference : null;
+}

package/dist/reference/verseId.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Verse ids encode book/chapter/verse as a single integer: BBCCCVVV
+ * (bookId * 1_000_000 + chapter * 1_000 + verse). This keeps verse ids
+ * sortable, stable across imports, and cheap to index in SQLite.
+ */
+export interface VerseLocation {
+    bookId: number;
+    chapter: number;
+    verse: number;
+}
+export declare function makeVerseId(bookId: number, chapter: number, verse: number): number;
+export declare function parseVerseId(verseId: number): VerseLocation;

package/dist/reference/verseId.js

@@ -0,0 +1,36 @@
+/**
+ * Verse ids encode book/chapter/verse as a single integer: BBCCCVVV
+ * (bookId * 1_000_000 + chapter * 1_000 + verse). This keeps verse ids
+ * sortable, stable across imports, and cheap to index in SQLite.
+ */
+const MIN_BOOK_ID = 1;
+const MAX_BOOK_ID = 66;
+const MIN_CHAPTER = 1;
+const MAX_CHAPTER = 999;
+const MIN_VERSE = 1;
+const MAX_VERSE = 999;
+export function makeVerseId(bookId, chapter, verse) {
+    if (!Number.isInteger(bookId) || bookId < MIN_BOOK_ID || bookId > MAX_BOOK_ID) {
+        throw new Error(`makeVerseId: bookId ${bookId} is out of range 1-66`);
+    }
+    if (!Number.isInteger(chapter) || chapter < MIN_CHAPTER || chapter > MAX_CHAPTER) {
+        throw new Error(`makeVerseId: chapter ${chapter} is out of range 1-999`);
+    }
+    if (!Number.isInteger(verse) || verse < MIN_VERSE || verse > MAX_VERSE) {
+        throw new Error(`makeVerseId: verse ${verse} is out of range 1-999`);
+    }
+    return bookId * 1_000_000 + chapter * 1_000 + verse;
+}
+export function parseVerseId(verseId) {
+    if (!Number.isInteger(verseId) || verseId < 1_001_001 || verseId > 66_999_999) {
+        throw new Error(`parseVerseId: ${verseId} is not a valid verse id`);
+    }
+    const bookId = Math.floor(verseId / 1_000_000);
+    const chapter = Math.floor((verseId % 1_000_000) / 1_000);
+    const verse = verseId % 1_000;
+    // Re-validate via makeVerseId so range-checking logic isn't duplicated,
+    // and so a value like 1000000 (chapter 0) is rejected rather than
+    // silently accepted.
+    makeVerseId(bookId, chapter, verse);
+    return { bookId, chapter, verse };
+}

package/dist/tokenizer/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * THE shared tokenizer. Ported from LH Worship Setlist's
+ * `src/lib/bible/keywords.ts`, which already solved the hard part: a stopword
+ * list that covers KJV-era pronouns and verb forms, so modern lyric/query
+ * vocabulary matches archaic scripture text without every `thou`/`hath`
+ * polluting the result.
+ *
+ * "THE" is load-bearing. The build pipeline and the runtime MUST tokenize
+ * identically — corpus term profiles are precomputed at build time, and a
+ * runtime that stems differently would compare mismatched vocabularies and
+ * silently return wrong rankings. That is why TOKENIZER_VERSION is stamped
+ * into the artifact and verified on open, and why this module has no options
+ * parameter: a per-caller tokenizer setting is exactly the bug it prevents.
+ */
+/**
+ * Normalize one surface form to its index token: archaic fold, then stem.
+ * Words shorter than 3 characters and stopwords return null.
+ */
+export declare function normalizeToken(raw: string): string | null;
+/**
+ * Significant tokens in order of first occurrence, deduplicated. This is the
+ * set form used for overlap scoring and concept-lexicon matching.
+ */
+export declare function significantWords(text: string): string[];
+/**
+ * Positional token stream: every significant occurrence, with the word index
+ * it came from. Proximity scoring (intent 3) needs positions, which the
+ * deduplicated form above deliberately discards. Positions are indices into
+ * the raw word sequence, so distance survives dropped stopwords rather than
+ * being compressed by them.
+ */
+export declare function tokenStream(text: string): readonly {
+    token: string;
+    position: number;
+}[];
+/** Exposed for gate tooling and tests; never mutate. */
+export declare const TOKENIZER_STOPWORD_COUNT: number;
+export declare const TOKENIZER_ARCHAIC_FORM_COUNT: number;
+export declare const TOKENIZER_LEMMA_COUNT: number;

package/dist/tokenizer/index.js

@@ -0,0 +1,207 @@
+/**
+ * THE shared tokenizer. Ported from LH Worship Setlist's
+ * `src/lib/bible/keywords.ts`, which already solved the hard part: a stopword
+ * list that covers KJV-era pronouns and verb forms, so modern lyric/query
+ * vocabulary matches archaic scripture text without every `thou`/`hath`
+ * polluting the result.
+ *
+ * "THE" is load-bearing. The build pipeline and the runtime MUST tokenize
+ * identically — corpus term profiles are precomputed at build time, and a
+ * runtime that stems differently would compare mismatched vocabularies and
+ * silently return wrong rankings. That is why TOKENIZER_VERSION is stamped
+ * into the artifact and verified on open, and why this module has no options
+ * parameter: a per-caller tokenizer setting is exactly the bug it prevents.
+ */
+// Common English function words plus KJV-era pronouns/verb forms.
+const STOPWORDS = new Set([
+    // articles / conjunctions / prepositions
+    'the', 'a', 'an', 'and', 'or', 'but', 'nor', 'for', 'so', 'yet',
+    'of', 'in', 'on', 'at', 'to', 'by', 'with', 'from', 'up', 'down',
+    'into', 'onto', 'over', 'under', 'after', 'before', 'between', 'through',
+    'about', 'above', 'below', 'again', 'further', 'then', 'once', 'than',
+    'as', 'if', 'because', 'while', 'until', 'unless', 'though', 'although',
+    'out', 'off', 'not', 'no', 'too', 'very', 'just', 'also', 'only',
+    'own', 'same', 'such',
+    // pronouns
+    'i', 'me', 'my', 'mine', 'myself',
+    'we', 'us', 'our', 'ours', 'ourselves',
+    'you', 'your', 'yours', 'yourself', 'yourselves',
+    'he', 'him', 'his', 'himself',
+    'she', 'her', 'hers', 'herself',
+    'it', 'its', 'itself',
+    'they', 'them', 'their', 'theirs', 'themselves',
+    'who', 'whom', 'whose', 'which', 'what', 'this', 'that', 'these', 'those',
+    // verbs (be/have + modals)
+    'am', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'having',
+    'will', 'would', 'can', 'could', 'may', 'might', 'must', 'shall', 'should',
+    // NOTE: the do-family (do/does/did/doing/done) is deliberately ABSENT.
+    // Setlist's list dropped it as auxiliary noise, which is correct for bare
+    // overlap counting but wrong here: "doers of the word", "hearing and
+    // doing", and "he who hears and does" are the exact theological vocabulary
+    // this engine exists to match. Keeping it costs little, because unlike
+    // Setlist we weight tokens statistically — a token this common earns a
+    // near-zero IDF contribution and can never clear the G5 distinctiveness
+    // floor to enter a passage term profile. Frequency is handled by
+    // statistics; the stopword list is too blunt an instrument to decide which
+    // verbs carry doctrine.
+    // misc high-frequency function words
+    'there', 'here', 'when', 'where', 'why', 'how', 'all', 'each', 'every',
+    'both', 'few', 'more', 'most', 'other', 'some', 'any', 'one', 'upon',
+    'let', 'lest', 'yes',
+    // KJV-isms
+    'thee', 'thou', 'thy', 'thine', 'ye',
+    'hath', 'hast', 'doth', 'dost', 'art', 'wilt', 'wouldst', 'shalt', 'shouldst',
+    'unto', 'verily', 'behold', 'saith', 'whence', 'whither', 'hither', 'thither',
+    'wherefore', 'forasmuch', 'peradventure', 'howbeit', 'thereof', 'thereto',
+    'herein', 'wherein', 'whereof', 'thereby', 'hereby', 'hereof', 'whosoever',
+]);
+/**
+ * Archaic verb forms folded to their modern stem BEFORE stemming, so a query
+ * typed as "hearing and doing" can reach text that reads "he that heareth
+ * these sayings of mine, and doeth them". Suffix stripping alone cannot do
+ * this: `doeth` -> `doeth` under any -s/-ed/-ing rule.
+ *
+ * Deliberately a short, reviewed table of high-frequency forms rather than a
+ * generative rule — `-eth`/`-est` stripping produces false merges (`death`,
+ * `breath`, `harvest`) that would quietly corrupt term profiles. Growth of
+ * this table is a reviewed change like any other data addition.
+ */
+const ARCHAIC_FORMS = new Map([
+    ['doeth', 'do'], ['doest', 'do'],
+    ['heareth', 'hear'], ['hearest', 'hear'],
+    ['keepeth', 'keep'], ['keepest', 'keep'],
+    ['believeth', 'believe'], ['believest', 'believe'],
+    ['walketh', 'walk'], ['walkest', 'walk'],
+    ['speaketh', 'speak'], ['speakest', 'speak'],
+    ['loveth', 'love'], ['lovest', 'love'],
+    ['giveth', 'give'], ['givest', 'give'],
+    ['knoweth', 'know'], ['knowest', 'know'],
+    ['maketh', 'make'], ['makest', 'make'],
+    ['cometh', 'come'], ['comest', 'come'],
+    ['seeketh', 'seek'], ['seekest', 'seek'],
+    ['calleth', 'call'], ['callest', 'call'],
+    ['dwelleth', 'dwell'], ['dwellest', 'dwell'],
+    ['abideth', 'abide'], ['abidest', 'abide'],
+    ['trusteth', 'trust'], ['trustest', 'trust'],
+    ['worketh', 'work'], ['workest', 'work'],
+    ['receiveth', 'receive'], ['sendeth', 'send'],
+    ['buildeth', 'build'], ['heareth', 'hear'],
+    ['obeyeth', 'obey'], ['forgiveth', 'forgive'],
+]);
+/**
+ * Irregular and short-word lemmas that suffix stemming provably cannot reach.
+ *
+ * The stemmer refuses to cut below a 4-character stem — a necessary rule that
+ * prevents `ties`->`t`, but one that silently strands the shortest and most
+ * common verbs: `doing` (5-3 < 4), `does`, `done`, `heard`. Those are exactly
+ * the words in "hearing and doing", so without this table the engine's
+ * motivating query cannot match the text it is meant to find.
+ *
+ * Agent nouns fold to their verb (`doer` -> `do`) because "doers of the word"
+ * and "he who does the word" are the same claim, and a search for one must
+ * find the other.
+ *
+ * Reviewed table, not a generative rule: every entry is a deliberate merge,
+ * because a wrong merge is invisible at query time and corrupts every term
+ * profile built from it.
+ */
+const IRREGULAR_LEMMAS = new Map([
+    // do-family: the concept "hearing and doing" lives or dies here
+    ['does', 'do'], ['doing', 'do'], ['done', 'do'], ['did', 'do'],
+    ['doer', 'do'], ['doers', 'do'],
+    // hear-family: short forms and agent nouns
+    ['heard', 'hear'], ['hearer', 'hear'], ['hearers', 'hear'],
+    ['hears', 'hear'], ['hearken', 'hear'], ['hearkened', 'hear'],
+    // other high-frequency irregulars whose stems fall below the 4-char floor
+    ['said', 'say'], ['says', 'say'], ['saith', 'say'], ['sayings', 'say'],
+    ['saying', 'say'], ['spoken', 'speak'], ['spoke', 'speak'],
+    ['kept', 'keep'], ['keeps', 'keep'],
+    ['gave', 'give'], ['given', 'give'], ['gives', 'give'],
+    ['knew', 'know'], ['known', 'know'], ['knows', 'know'],
+    ['built', 'build'], ['builds', 'build'],
+    ['sought', 'seek'], ['seeks', 'seek'],
+    ['stood', 'stand'], ['stands', 'stand'],
+    ['fell', 'fall'], ['fallen', 'fall'], ['falls', 'fall'],
+    ['obeys', 'obey'], ['obeyed', 'obey'],
+]);
+/** Light suffix stemming: -ing, -ies, -ed, -es, -s. Stem must stay >= 4 chars. */
+function stem(word) {
+    if (word.endsWith('ing') && word.length - 3 >= 4)
+        return word.slice(0, -3);
+    if (word.endsWith('ies') && word.length - 3 >= 4)
+        return `${word.slice(0, -3)}y`;
+    if (word.endsWith('ed') && word.length - 2 >= 4)
+        return word.slice(0, -2);
+    if (word.endsWith('es') && word.length - 2 >= 4)
+        return word.slice(0, -2);
+    if (word.endsWith('s') && !word.endsWith('ss') && word.length - 1 >= 4) {
+        return word.slice(0, -1);
+    }
+    return word;
+}
+/** Split into lowercase word forms with punctuation and apostrophes removed. */
+function rawWords(text) {
+    return text
+        .toLowerCase()
+        .replace(/['‘’‛ʼ]/g, '')
+        .replace(/[^\p{L}\p{N}\s]/gu, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+}
+/**
+ * Normalize one surface form to its index token: archaic fold, then stem.
+ * Words shorter than 3 characters and stopwords return null.
+ */
+export function normalizeToken(raw) {
+    // Length floor applies to the surface form, but AFTER lemma lookup, so
+    // two-letter results of a deliberate merge (none today) stay reachable.
+    if (STOPWORDS.has(raw))
+        return null;
+    const modern = ARCHAIC_FORMS.get(raw) ?? raw;
+    const lemma = IRREGULAR_LEMMAS.get(modern);
+    if (lemma !== undefined)
+        return STOPWORDS.has(lemma) ? null : lemma;
+    if (raw.length < 3)
+        return null;
+    const stemmed = stem(modern);
+    if (STOPWORDS.has(stemmed))
+        return null;
+    return stemmed;
+}
+/**
+ * Significant tokens in order of first occurrence, deduplicated. This is the
+ * set form used for overlap scoring and concept-lexicon matching.
+ */
+export function significantWords(text) {
+    const seen = new Set();
+    const result = [];
+    for (const raw of rawWords(text)) {
+        const token = normalizeToken(raw);
+        if (token === null || seen.has(token))
+            continue;
+        seen.add(token);
+        result.push(token);
+    }
+    return result;
+}
+/**
+ * Positional token stream: every significant occurrence, with the word index
+ * it came from. Proximity scoring (intent 3) needs positions, which the
+ * deduplicated form above deliberately discards. Positions are indices into
+ * the raw word sequence, so distance survives dropped stopwords rather than
+ * being compressed by them.
+ */
+export function tokenStream(text) {
+    const stream = [];
+    rawWords(text).forEach((raw, position) => {
+        const token = normalizeToken(raw);
+        if (token !== null)
+            stream.push({ token, position });
+    });
+    return stream;
+}
+/** Exposed for gate tooling and tests; never mutate. */
+export const TOKENIZER_STOPWORD_COUNT = STOPWORDS.size;
+export const TOKENIZER_ARCHAIC_FORM_COUNT = ARCHAIC_FORMS.size;
+export const TOKENIZER_LEMMA_COUNT = IRREGULAR_LEMMAS.size;

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The consumer-facing contract. Ported from Maskil's
+ * `app/src/scripture/types.ts` and generalized so Setlist and Versed can use
+ * the same engine without inheriting Maskil-shaped assumptions.
+ *
+ * `ContentQueryPort` is the ONLY seam to the outside world. Maskil supplies
+ * OP-SQLite on device, the pipeline and eval harness supply better-sqlite3 in
+ * Node, and a future hosted consumer could supply an HTTP-backed adapter —
+ * none of which the engine knows or cares about.
+ */
+import type { Reason } from './reasons/types.js';
+export type ContentScalar = string | number | boolean | null | ArrayBuffer | ArrayBufferView;
+export interface ContentQueryResult {
+    readonly rows: readonly Readonly<Record<string, ContentScalar>>[];
+}
+export interface ContentQueryPort {
+    execute(query: string, params?: readonly ContentScalar[]): Promise<ContentQueryResult>;
+    close(): Promise<void>;
+}
+export interface ScriptureVerse {
+    readonly id: number;
+    readonly verseId: number;
+    readonly translationId: number;
+    readonly translationCode: string;
+    readonly bookId: number;
+    readonly bookName: string;
+    readonly chapter: number;
+    readonly verse: number;
+    readonly text: string;
+}
+export interface ScripturePassage {
+    readonly reference: string;
+    readonly bookId: number;
+    readonly chapterCount: number;
+    readonly startChapter: number;
+    readonly endChapter: number;
+    readonly verses: readonly ScriptureVerse[];
+}
+/**
+ * Every result carries the identities that make it reproducible. A consumer
+ * can record `(engineVersion, corpusFingerprint, layerFingerprint, query)`
+ * and any other consumer, on any platform, can regenerate the identical
+ * ordering. This is the machine-checkable form of the "deterministic" claim.
+ */
+export interface ResultIdentity {
+    readonly engineVersion: string;
+    /** Identifies the scripture text. */
+    readonly corpusFingerprint: string;
+    /**
+     * Identifies the curated concept and homiletical layers.
+     *
+     * Separate from the corpus fingerprint because they change for different
+     * reasons and at different rates — and because without it, editing a
+     * concept would silently alter rankings while every published identity
+     * stayed the same. Reproducing a result requires BOTH.
+     */
+    readonly layerFingerprint: string;
+}
+export interface DiscoveryResult {
+    readonly targetId: string;
+    readonly reference: string;
+    readonly excerpt: string;
+    readonly score: number;
+    readonly reasons: readonly Reason[];
+}
+export type ResearchOutcome = {
+    readonly kind: 'reference';
+    readonly passage: ScripturePassage;
+} | {
+    readonly kind: 'invalid-reference';
+    readonly query: string;
+} | {
+    readonly kind: 'discovery';
+    readonly query: string;
+    readonly results: readonly DiscoveryResult[];
+};
+export type ResearchResult = ResearchOutcome & ResultIdentity;
+/** Concept-resolution output for `engine.themes()`. */
+export interface ConceptMatch {
+    readonly conceptId: string;
+    readonly label: string;
+    /** Which lexicon entry matched, so the UI can show why this concept fired. */
+    readonly matchedOn: string;
+    readonly anchors: readonly string[];
+}
+/** `engine.passage()` — a lookup, with invalid references typed rather than thrown. */
+export type PassageResult = ({
+    readonly kind: 'passage';
+    readonly passage: ScripturePassage;
+} & ResultIdentity) | ({
+    readonly kind: 'invalid-reference';
+    readonly query: string;
+} & ResultIdentity);
+/**
+ * `engine.related()` — what a curated source connects to a passage.
+ *
+ * Deliberately NOT "verses that resemble this one". Every entry here exists
+ * because a human recorded a link: a cross-reference edge, or a concept whose
+ * anchors include this passage. Similarity is what `research()` does.
+ */
+export type RelatedResult = ({
+    readonly kind: 'related';
+    readonly reference: string;
+    /** Concepts whose curated anchors include this passage. */
+    readonly concepts: readonly ConceptMatch[];
+    readonly results: readonly DiscoveryResult[];
+} & ResultIdentity) | ({
+    readonly kind: 'invalid-reference';
+    readonly query: string;
+} & ResultIdentity);
+/**
+ * Multi-field input for `engine.forSong()`.
+ *
+ * Setlist matches a sermon theme to songs; Maskil starts from a song being
+ * written. Both need more than one field, and neither wants to pre-concatenate
+ * them, because the fields differ in evidential weight — a stated theme is a
+ * claim about meaning, a lyric line is raw text that happens to be present.
+ */
+export interface SongInput {
+    readonly title?: string;
+    readonly themes?: readonly string[];
+    readonly lyrics?: string;
+    /** A passage the song is built on. Seeds curated expansion, not text search. */
+    readonly foundationalRef?: string;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * The consumer-facing contract. Ported from Maskil's
+ * `app/src/scripture/types.ts` and generalized so Setlist and Versed can use
+ * the same engine without inheriting Maskil-shaped assumptions.
+ *
+ * `ContentQueryPort` is the ONLY seam to the outside world. Maskil supplies
+ * OP-SQLite on device, the pipeline and eval harness supply better-sqlite3 in
+ * Node, and a future hosted consumer could supply an HTTP-backed adapter —
+ * none of which the engine knows or cares about.
+ */
+export {};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@jestek-dev/scripture-engine",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Pure deterministic Scripture retrieval and ranking core. Zero I/O, zero runtime AI.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  }
+}