@jestek-dev/scripture-engine 0.7.1 → 0.14.0

package/dist/tokenizer/index.js

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

package/dist/types.d.ts

@@ -9,6 +9,7 @@
  * none of which the engine knows or cares about.
  */
 import type { Reason } from './reasons/types.js';
+import type { ReferenceSuggestion } from './reference/reference.js';
 export type ContentScalar = string | number | boolean | null | ArrayBuffer | ArrayBufferView;
 export interface ContentQueryResult {
     readonly rows: readonly Readonly<Record<string, ContentScalar>>[];
@@ -56,12 +57,94 @@ export interface ResultIdentity {
      */
     readonly layerFingerprint: string;
 }
+/**
+ * One member verse of a grouped (merged) result, its evidence uncollapsed
+ * (0.14.0/CO-3 PR 2). The merged row's reasons are strongest-per-label across
+ * the group; this is where a consumer finds what EACH verse contributed —
+ * "every verse's own evidence still visible" is part of the grouping design,
+ * not an optional nicety.
+ */
+export interface GroupedVerse {
+    readonly targetId: string;
+    readonly reference: string;
+    readonly excerpt: string;
+    readonly score: number;
+    readonly reasons: readonly Reason[];
+}
+/**
+ * Why a merged result's verses travel together (0.14.0/CO-3 PR 2). A typed
+ * field, deliberately NOT a `Reason`: reasons must correspond to scoring
+ * evidence, and grouping contributes ZERO points — the merged row's score is
+ * the max of its members, never a sum. The grouping cites a countable fact
+ * and names its source; nothing theological is adjudicated (covenant 6).
+ */
+export interface ResultGrouping {
+    /**
+     * The full span of the grouping unit — the curated anchor span, the alias
+     * verse range, or the derived pericope. The result row's own `reference`
+     * spans only the verses that actually surfaced (the hits), which may be a
+     * subset of this section.
+     */
+    readonly section: {
+        /** Label of the full section span, e.g. "Psalms 136:1-26". */
+        readonly reference: string;
+        readonly startVerseId: number;
+        readonly endVerseId: number;
+    };
+    readonly provenance: {
+        /**
+         * Manifest source id the grouping stands on: the anchor's own source(s)
+         * for an anchor-span merge ('+'-joined ascending when several agree,
+         * e.g. 'editorial'), 'hymn-aliases' for an alias verse range, or
+         * 'openbible-sections' for the pericope path. Authority order is fixed:
+         * an anchor span is checked first, so pericope provenance never usurps
+         * anchor provenance.
+         */
+        readonly sourceId: string;
+        /** Human-facing attribution, e.g. "OpenBible section boundaries (CC BY)". */
+        readonly label: string;
+        /**
+         * Pericope groups only: the summed boundary vote at the section's start
+         * verse — the exact number the artifact stores (how many of the 20
+         * surveyed translations start a section there). A countable structural
+         * fact, never a relevance score; the explanation and the shipped data
+         * cannot disagree because this is read from the same row.
+         */
+        readonly boundaryVotes?: number;
+    };
+}
 export interface DiscoveryResult {
     readonly targetId: string;
     readonly reference: string;
     readonly excerpt: string;
     readonly score: number;
     readonly reasons: readonly Reason[];
+    /**
+     * Additive (0.14.0/CO-3 PR 2): present exactly when this row is a merged
+     * passage-level result — the member verses in canonical order, each with
+     * its own uncollapsed evidence. Absent on single-verse rows.
+     */
+    readonly verses?: readonly GroupedVerse[];
+    /**
+     * Additive (0.14.0/CO-3 PR 2): present exactly when `verses` is — why the
+     * members travel together, citing the source that drew the boundary.
+     */
+    readonly grouping?: ResultGrouping;
+}
+/**
+ * One cited spelling correction (0.12.0/QR-5). Corrections are never silent:
+ * every substituted token is reported with the SURFACE form the user typed
+ * (never the stem the tokenizer made of it), the vocabulary term substituted,
+ * and the verified integer Damerau distance that justifies it — the same
+ * citation the token chips render as `(corrected from "<typed>")`.
+ */
+export interface SpellingCorrection {
+    /** What the user typed (lowercased surface form), e.g. "beleived". */
+    readonly typed: string;
+    /** The vocabulary term substituted, e.g. "believ". */
+    readonly corrected: string;
+    /** Verified integer Damerau–Levenshtein distance — the citation. */
+    readonly distance: number;
 }
 export type ResearchOutcome = {
     readonly kind: 'reference';
@@ -69,10 +152,27 @@ export type ResearchOutcome = {
 } | {
     readonly kind: 'invalid-reference';
     readonly query: string;
+    /**
+     * Additive (0.11.0/QR-4): a cited did-you-mean on the dead end — the
+     * unique in-policy near-miss book, the validated reference it implies,
+     * and the edit distance that justifies the guess. Suggestion only:
+     * the engine NEVER silently opens a guessed passage; consumers render
+     * it as a question ("did you mean Philippians 4:13?").
+     */
+    readonly suggestion?: ReferenceSuggestion;
 } | {
     readonly kind: 'discovery';
     readonly query: string;
     readonly results: readonly DiscoveryResult[];
+    /**
+     * Additive (0.12.0/QR-5): present iff `research()` substituted
+     * corrections for out-of-vocabulary tokens — the machine-readable
+     * citation consumers render (J32). Absent means nothing was corrected;
+     * a word in ANY vocabulary is never rewritten (the OOV gate).
+     * `forSong()` never corrects, so its discovery outcome never carries
+     * this field.
+     */
+    readonly corrections?: readonly SpellingCorrection[];
 };
 export type ResearchResult = ResearchOutcome & ResultIdentity;
 /** Concept-resolution output for `engine.themes()`. */
@@ -90,6 +190,8 @@ export type PassageResult = ({
 } & ResultIdentity) | ({
     readonly kind: 'invalid-reference';
     readonly query: string;
+    /** Additive (0.11.0/QR-4): see ResearchOutcome's invalid-reference. */
+    readonly suggestion?: ReferenceSuggestion;
 } & ResultIdentity);
 /**
  * `engine.related()` — what a curated source connects to a passage.
@@ -107,6 +209,8 @@ export type RelatedResult = ({
 } & ResultIdentity) | ({
     readonly kind: 'invalid-reference';
     readonly query: string;
+    /** Additive (0.11.0/QR-4): see ResearchOutcome's invalid-reference. */
+    readonly suggestion?: ReferenceSuggestion;
 } & ResultIdentity);
 /**
  * Multi-field input for `engine.forSong()`.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@jestek-dev/scripture-engine",
-  "version": "0.7.1",
+  "version": "0.14.0",
   "type": "module",
   "description": "Pure deterministic Scripture retrieval and ranking core. Zero I/O, zero runtime AI.",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jestek-dev/scripture-search-engine.git",
@@ -18,6 +19,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
   "files": [
@@ -30,6 +35,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
+    "fast-check": "4.9.0",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
   }