calliope-ts 0.0.2 → 0.0.3

package/dist/scansion.js

@@ -567,10 +567,20 @@ function buildScansionString(syls, feet, ius) {
     return out.join('|');
 }
 // ─── DISPLAY / NAMING HELPERS ──────────────────────────────────────
+// Greek-numeral foot-length names, exhaustive through 20 (icosameter) per the
+// maintainer's standardised nomenclature.  Long lines that are genuinely metrical
+// deserve a real meter name rather than the "N-feet" othering, so the ladder runs
+// all the way up; beyond 20 the bare "N-feet" fallback remains (lines that long
+// are almost never integrally metrical, and the prose-likeness hedge handles them).
+const LINE_LENGTH_NAMES = [
+    '', 'monometer', 'dimeter', 'trimeter', 'tetrameter', 'pentameter',
+    'hexameter', 'heptameter', 'octameter', 'nonometer', 'decameter',
+    'hendecameter', 'dodecameter', 'triskaidecameter', 'tetradecameter',
+    'pentadecameter', 'hexadecameter', 'heptadecameter', 'octadecameter',
+    'enneadecameter', 'icosameter',
+];
 function lineLengthName(feet) {
-    const names = ['', 'monometer', 'dimeter', 'trimeter', 'tetrameter', 'pentameter',
-        'hexameter', 'heptameter', 'octameter', 'nonameter', 'decameter'];
-    return names[feet] || `${feet}-feet`;
+    return LINE_LENGTH_NAMES[feet] || `${feet}-feet`;
 }
 // ─── TOP-LEVEL METER SCORING ────────────────────────────────────────
 // A meter's small intrinsic prior.  Iamb is the unmarked default of English
@@ -583,6 +593,7 @@ const METER_PRIOR = { iambic: 0.02 };
 // enough that it never overturns a clearly-duple line.
 const TERNARY_BIAS = 0.02;
 const TERNARY_METERS = new Set(['anapestic', 'dactylic', 'amphibrachic', 'bacchic']);
+const DUPLE_METERS = new Set(['iambic', 'trochaic']);
 // Weights against the (0..1) normalised fit fraction.
 const REDGE_WEIGHT = 0.28; // right-edge (key-stress) agreement — disambiguates polarity
 const CLEAN_WEIGHT = 0.12; // share of feet realised cleanly (real beats, no substitution)
@@ -613,6 +624,74 @@ function onsetBonus(flat, meter) {
         return FALLING_METERS.has(meter) ? ONSET_WEIGHT : 0;
     return RISING_METERS.has(meter) ? ONSET_WEIGHT : 0;
 }
+// ─── METRICALITY ASSESSMENT (Option-0 prose-likeness hedge) ─────────
+//
+// A single decontextualised line is, in generative-metrics terms, almost always
+// fittable to SOME grid (English prose alternates; phrase-ends are right-strong),
+// so absolute fit cannot separate prose from verse — empirically, loose real
+// verse ("Half a league…", Prufrock) scores BELOW expository prose.  What DOES
+// separate them is non-periodicity accumulated AT LENGTH: a long run of text that
+// (a) commits to no meter — its top candidates straddle BOTH the rising/falling
+// and the duple/triple divides within a hair — and (b) realises that best fit only
+// weakly.  This is a deliberately HIGH-PRECISION gate: it fires only on the
+// unmistakable un-lineated-prose case and never on short, loose, or ternary verse
+// (the project's prized cases).  It is advisory — it changes the displayed verdict
+// WORDING only; the scansion, fit, ranking, foot count and certainty are intact.
+// Necessary length: real metrical lines top out around the hepta-/octameter, so
+// 9+ feet is almost never an integral line.  Combined (AND) with the commitment
+// and confidence gates below, clean verse that happens to exceed this length keeps
+// a healthy margin and certainty and is therefore spared.
+const PROSE_MIN_FEET = 9;
+const PROSE_MAX_MARGIN = 0.10; // top1 − top2: prose does not commit to one meter
+// …and realises even its best fit only weakly.  This ceiling is an empirical
+// calibration against the relative-stress contour, NOT a theory — re-fit when the
+// contour changes.  Verified (2026-06-21, after the dependency-driven ϕ rebuild):
+// across 1736 real litlab verse lines, ZERO pass the length+margin+straddle gates,
+// so the certainty ceiling never gates real verse — its only job is to admit the
+// genuinely-prose case, which the improved contour now realises at 68%.
+const PROSE_MAX_CERTAINTY = 70;
+/** Does the top-3 ranking straddle BOTH polarity (rising/falling) AND foot-size
+ *  (duple/triple)?  The fingerprint of a contour equidistant from every meter —
+ *  present in prose, absent in committed verse (whose ties stay within a family). */
+function rankingStraddles(ranking) {
+    const top = ranking.slice(0, 3).map(r => r.meter);
+    const rising = top.some(m => RISING_METERS.has(m));
+    const falling = top.some(m => FALLING_METERS.has(m));
+    const triple = top.some(m => TERNARY_METERS.has(m));
+    const duple = top.some(m => DUPLE_METERS.has(m));
+    return rising && falling && triple && duple;
+}
+/**
+ * If a line reads as plausible prose (see above), return the advisory hedge
+ * string; otherwise undefined.  Reads only fields already present on the detail,
+ * so it runs as a late, non-destructive pipeline pass (`applyMetricalityLayer`).
+ */
+export function metricalityVerdict(detail) {
+    if (detail.meterName === 'free verse')
+        return undefined; // already non-committal
+    if (detail.rhythmNote)
+        return undefined; // accentual/dolnik already named
+    if (detail.footCount < PROSE_MIN_FEET)
+        return undefined;
+    const ranking = detail.ranking;
+    if (!ranking || ranking.length < 2)
+        return undefined;
+    const margin = ranking[0].score - ranking[1].score;
+    if (margin >= PROSE_MAX_MARGIN)
+        return undefined; // commits to one meter
+    if (detail.certainty >= PROSE_MAX_CERTAINTY)
+        return undefined;
+    if (!rankingStraddles(ranking))
+        return undefined;
+    return `No consistent metered rhythm(s) discerned.  Reads as plausible prose. `
+        + `(Closest fit: ${detail.meter}, ${detail.certainty}%)`;
+}
+/** Set `detail.metricalityNote` on every line that reads as plausible prose.
+ *  Non-destructive: only the new advisory field is written. */
+export function applyMetricalityLayer(details) {
+    for (const d of details)
+        d.metricalityNote = metricalityVerdict(d);
+}
 export function scoreMeters(keyStresses, words, ius, force) {
     const flat = flattenSyllables(words, ius);
     const N = flat.length;
@@ -872,7 +951,9 @@ export function applyRhythmLayer(details) {
                     const pooled = profiles.flatMap(p => p.intervals);
                     const family = intervalFamily(pooled);
                     const flavour = family === 'dolnik' ? 'dolnik' : 'accentual';
-                    note = `alternating ${evens[0]}·${odds[0]}-ictus ${flavour}`;
+                    // "4/3 ♪beat accentual" — no "alternating" (too long), "/" not "·" (so
+                    // "4·3" is not misread as 12), ♪ marks that these are beat counts.
+                    note = `${evens[0]}/${odds[0]} ♪beat ${flavour}`;
                 }
                 else {
                     // Constant ictus count (mode covering ≥70% of lines, total spread ≤1).
@@ -891,9 +972,13 @@ export function applyRhythmLayer(details) {
                         // duple/ternary pooled intervals with varying syllable counts =
                         // anacrusis/clausula variation only — classical machinery's domain.
                     }
-                    else if (spread >= 3) {
-                        note = 'free verse (heterometric)';
-                    }
+                    // NB: a high-spread stanza with NO constant beat count is NOT stamped
+                    // here.  Forcing a "heterometric" rhythmNote onto every line both
+                    // polluted the per-line display and (because the continuity pass is
+                    // gated by rhythmNote) blocked the stanza-continuity rename.  Lines
+                    // instead keep their own meter and get a per-line dolnik/accentual
+                    // reading below; the whole-poem heterometric observation is reported
+                    // by the synopsis (summarizePoem), outside the per-line section.
                 }
                 if (note)
                     for (const d of lines)
@@ -939,20 +1024,34 @@ export function applyStanzaConsensus(details, tie = 0.975) {
             continue;
         counts.set(d.meterName, (counts.get(d.meterName) ?? 0) + 1);
     }
-    // Dominant meter = the strict, unique plurality (≥2 lines).
+    // Dominant meter = the strict plurality (≥2 lines).  A TIED plurality is broken
+    // by each tied family's total ranking-score mass across the stanza (2026-07-02):
+    // catalectic lines make sibling readings trade wins line-by-line (The Raven's
+    // 15-syllable lines flip trochaic-octameter ↔ "iambic heptameter", tying the
+    // count 3–3), but the family the stanza actually commits to carries more total
+    // fit mass — so the tie is evidence-weighted, never a coin toss or a give-up.
     let dominant = '';
     let max = 0;
-    let tied = false;
+    const atMax = [];
     for (const [m, c] of counts) {
         if (c > max) {
             max = c;
-            dominant = m;
-            tied = false;
+            atMax.length = 0;
+            atMax.push(m);
         }
         else if (c === max)
-            tied = true;
+            atMax.push(m);
     }
-    if (max < 2 || tied || !dominant)
+    if (max < 2)
+        return;
+    if (atMax.length === 1) {
+        dominant = atMax[0];
+    }
+    else {
+        const mass = (name) => details.reduce((s, d) => s + (d.ranking?.find(r => r.meter === name)?.score ?? 0), 0);
+        dominant = atMax.reduce((a, b) => (mass(b) > mass(a) ? b : a));
+    }
+    if (!dominant)
         return;
     // Ternary ANACRUSIS ANCHOR (Gasparov): when the stanza's dominant meter is
     // ternary, the family is fixed by the stanza's anacrusis profile, not by the
@@ -968,8 +1067,29 @@ export function applyStanzaConsensus(details, tie = 0.975) {
             if (!TERNARY_METERS.has(d.meterName))
                 continue;
             const p = ictusProfile(d.scansion);
-            if (p.ictuses >= 2 && p.anacrusis <= 2)
-                anacs.push(p.anacrusis);
+            if (p.ictuses < 2)
+                continue;
+            let anac = p.anacrusis;
+            if (RISING_METERS.has(d.meterName)) {
+                // For a RISING line the raw profile's Attridge promotions pollute the
+                // anacrusis: a promoted 'w'/'n' upbeat at position 0 ("'TWAS the night
+                // before…") reads as anacrusis 0 and vetoes the anapest call.  The
+                // family anchor wants the SCHEME's first beat, so measure to the first
+                // STRONG (m/s) ictus instead.  Falling lines keep the raw profile —
+                // their genuine first beat is often a light 'n' ("HALF a league").
+                const letters = d.scansion.replace(/[^xwnms]/g, '');
+                const firstStrong = [...letters].findIndex(c => c === 's' || c === 'm');
+                if (firstStrong >= 0)
+                    anac = firstStrong;
+                // Over-stressed anacrusis (Gasparov): an extra stress on the upbeat
+                // does NOT change the meter — a rising line whose first strong sits at
+                // position 0 ("NOT a creature was stirring…") has a stressed upbeat,
+                // not a dactylic opening; drop it from the anchor vote entirely.
+                if (anac === 0)
+                    continue;
+            }
+            if (anac <= 2)
+                anacs.push(anac);
         }
         if (anacs.length >= 2) {
             const has = (v) => anacs.includes(v);
@@ -995,9 +1115,16 @@ export function applyStanzaConsensus(details, tie = 0.975) {
         // spondaic anacrusis ("big BOOKS that are HURting…") lets the dactylic fit
         // edge out the stanza's amphibrachs by seizing the clash syllable as an
         // extra beat (Gasparov: an over-stressed anacrusis does NOT change the
-        // meter).  Non-sibling divergence keeps the stricter 0.975 near-tie.
-        const siblings = TERNARY_METERS.has(d.meterName)
-            && TERNARY_METERS.has(dominant);
+        // meter).  The DUPLE pair (iamb/trochee) are siblings in exactly the same
+        // sense (2026-07-02): a catalectic trochaic line IS an "iambic" grid plus
+        // an offset — The Raven's 15-syllable lines read trochaic-octameter or
+        // iambic-heptameter on the same beats — so a stanza committed to one duple
+        // family pulls near-tie sibling readings in at the same relaxed window.
+        // Non-sibling divergence keeps the stricter 0.975 near-tie.
+        const siblings = (TERNARY_METERS.has(d.meterName)
+            && TERNARY_METERS.has(dominant))
+            || (DUPLE_METERS.has(d.meterName)
+                && DUPLE_METERS.has(dominant));
         const threshold = siblings ? 0.95 : tie;
         if (own > 0 && dom >= own * threshold) {
             const lengthWord = d.meter.split(' ')[1] ?? '';

package/dist/semantics.d.ts

@@ -0,0 +1,44 @@
+import { ClsWord } from './types.js';
+/**
+ * A STRANDED preposition: an IN preposition whose complement has been extracted
+ * (wh-movement / relativisation / topicalisation), so it governs no object and
+ * sits clause-finally — "what are you waiting FOR", "…what you stare AT".  Such
+ * a preposition bears stress (it is not the reducible proclitic of "in the
+ * house").  Conservative: IN only (infinitival TO is excluded — "I want to go"
+ * is not stranding), no dependent, and clause-final (the canonical strand site).
+ */
+export declare function isStrandedPreposition(word: ClsWord, words: ClsWord[]): boolean;
+/**
+ * A CONTRASTIVE possessive: a possessive determiner (PRP$: thy/my/your/her…)
+ * in the elliptical contrast frame "X's … not/but MINE" — the contrast lifts
+ * the possessor out of reduction ("it was THY choice, not mine").  Tight by
+ * construction: requires a contrast marker (not/but/nor) adjacent to an
+ * absolute possessive somewhere in the clause, so an ordinary unfocused
+ * possessive ("I lost my way") is left alone.
+ */
+export declare function isContrastivePossessive(word: ClsWord, words: ClsWord[]): boolean;
+/**
+ * A fronted DEICTIC LOCATIVE "there"/"here" in locative inversion — "THERE
+ * could I marvel", "HERE could I rest".  FinNLP mis-tags the fronted locative
+ * as existential (EX / expl) or reduces it as a discourse adverb, flattening it
+ * to 'w'; but a fronted locative that triggers subject-aux inversion (an
+ * aux/modal immediately followed by a subject pronoun) is a stressed deictic
+ * focus, NOT the reduced existential of "there IS a house" (no inversion) or
+ * the presentational "there LIVED a king" (verb + NP, no inversion).
+ */
+export declare function isDeicticLocative(word: ClsWord, words: ClsWord[]): boolean;
+/**
+ * Imperative clause: the ROOT is a base-form verb (VB) with no overt subject
+ * (no NSUBJ dependent) — "Tell me…", "Do not go…".  Used by the nuclear pass:
+ * the accent falls on the verb / its object, not on a (dropped) subject, and an
+ * imperative-clause vocative is a direct address.
+ */
+export declare function isImperativeClause(words: ClsWord[]): boolean;
+/**
+ * A VOCATIVE (direct address): a noun tagged DISCOURSE/INTJ/DEP and set off by
+ * adjacent punctuation (a comma or "!"), in a clause that is imperative or
+ * subject-less — "Sing, O GODDESS…", "blow, BUGLE, blow".  Conservative: the
+ * noun must be comma/!-adjacent so an ordinary argument noun is not swept in.
+ */
+export declare function isVocative(word: ClsWord, words: ClsWord[]): boolean;
+//# sourceMappingURL=semantics.d.ts.map

package/dist/semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.d.ts","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAsBrC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAI9E;AAQD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAQhF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAS5D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAUnE"}

package/dist/semantics.js

@@ -0,0 +1,139 @@
+// semantics.ts — Prominence signals mined from the dependency parse + POS.
+//
+// Dependency roles ARE the semantic layer: NSUBJ=agent, DOBJ/IOBJ=patient/
+// recipient, OBL/ADVMOD/ADVCL=peripheral, PRP$=possessor, INTJ/DISCOURSE=
+// address.  A flat POS floor crushes function words that these configurations
+// reveal to be prominent — a STRANDED preposition ("what are you waiting FOR"),
+// a CONTRASTIVE possessive ("thy choice, not mine"), a VOCATIVE.  These
+// detectors recover that prominence from observable structure only (no semantic
+// guessing, no cross-poem givenness).  They are consumed by the relativiser
+// (stress.ts) as targeted floor RAISES, and by the nuclear pass (Phase 4).
+import { isPunctuation } from './parser.js';
+/** True if some other token has `word` as its dependency governor (i.e. word
+ *  has a complement/dependent of its own). */
+function hasDependent(word, words) {
+    for (const w of words) {
+        if (w !== word && w.dependency && w.dependency.governor === word)
+            return true;
+    }
+    return false;
+}
+/** Last non-punctuation token index in the sentence at/after `from`? */
+function isClauseFinal(word, words) {
+    const idx = words.indexOf(word);
+    if (idx < 0)
+        return false;
+    for (let k = idx + 1; k < words.length; k++) {
+        if (!isPunctuation(words[k].lexicalClass))
+            return false;
+    }
+    return true;
+}
+/**
+ * A STRANDED preposition: an IN preposition whose complement has been extracted
+ * (wh-movement / relativisation / topicalisation), so it governs no object and
+ * sits clause-finally — "what are you waiting FOR", "…what you stare AT".  Such
+ * a preposition bears stress (it is not the reducible proclitic of "in the
+ * house").  Conservative: IN only (infinitival TO is excluded — "I want to go"
+ * is not stranding), no dependent, and clause-final (the canonical strand site).
+ */
+export function isStrandedPreposition(word, words) {
+    if (word.lexicalClass !== 'IN')
+        return false;
+    if (hasDependent(word, words))
+        return false; // has a complement → ordinary preposition
+    return isClauseFinal(word, words);
+}
+/** Absolute / elliptical possessive pronouns used as the contrasted element. */
+const ABSOLUTE_POSSESSIVES = new Set([
+    'mine', 'thine', 'yours', 'hers', 'ours', 'theirs', 'his',
+]);
+const CONTRAST_MARKERS = new Set(['not', 'but', 'nor']);
+/**
+ * A CONTRASTIVE possessive: a possessive determiner (PRP$: thy/my/your/her…)
+ * in the elliptical contrast frame "X's … not/but MINE" — the contrast lifts
+ * the possessor out of reduction ("it was THY choice, not mine").  Tight by
+ * construction: requires a contrast marker (not/but/nor) adjacent to an
+ * absolute possessive somewhere in the clause, so an ordinary unfocused
+ * possessive ("I lost my way") is left alone.
+ */
+export function isContrastivePossessive(word, words) {
+    if (word.lexicalClass !== 'PRP$')
+        return false;
+    for (let i = 0; i + 1 < words.length; i++) {
+        const a = words[i].word.toLowerCase();
+        const b = words[i + 1].word.toLowerCase().replace(/['’]/g, '');
+        if (CONTRAST_MARKERS.has(a) && ABSOLUTE_POSSESSIVES.has(b))
+            return true;
+    }
+    return false;
+}
+/** Finite auxiliaries / modals whose appearance before a subject pronoun marks
+ *  subject-aux inversion. */
+const INVERSION_AUX = new Set(['MD', 'VBP', 'VBZ', 'VBD']);
+/**
+ * A fronted DEICTIC LOCATIVE "there"/"here" in locative inversion — "THERE
+ * could I marvel", "HERE could I rest".  FinNLP mis-tags the fronted locative
+ * as existential (EX / expl) or reduces it as a discourse adverb, flattening it
+ * to 'w'; but a fronted locative that triggers subject-aux inversion (an
+ * aux/modal immediately followed by a subject pronoun) is a stressed deictic
+ * focus, NOT the reduced existential of "there IS a house" (no inversion) or
+ * the presentational "there LIVED a king" (verb + NP, no inversion).
+ */
+export function isDeicticLocative(word, words) {
+    const lemma = word.word.toLowerCase().replace(/['’]/g, '');
+    if (lemma !== 'there' && lemma !== 'here')
+        return false;
+    const idx = words.indexOf(word);
+    // must be the first non-punctuation token (fronted)
+    let first = -1;
+    for (let i = 0; i < words.length; i++) {
+        if (!isPunctuation(words[i].lexicalClass)) {
+            first = i;
+            break;
+        }
+    }
+    if (idx !== first)
+        return false;
+    // subject-aux inversion: <there/here> <aux|modal> <subject pronoun>
+    const aux = words[idx + 1];
+    const subj = words[idx + 2];
+    return !!(aux && subj && INVERSION_AUX.has(aux.lexicalClass) && subj.lexicalClass === 'PRP');
+}
+/**
+ * Imperative clause: the ROOT is a base-form verb (VB) with no overt subject
+ * (no NSUBJ dependent) — "Tell me…", "Do not go…".  Used by the nuclear pass:
+ * the accent falls on the verb / its object, not on a (dropped) subject, and an
+ * imperative-clause vocative is a direct address.
+ */
+export function isImperativeClause(words) {
+    const root = words.find(w => w.dependency && w.dependency.dependentType === 'root');
+    if (!root)
+        return false;
+    if (root.lexicalClass !== 'VB' && root.lexicalClass !== 'VBP')
+        return false;
+    for (const w of words) {
+        if (w.dependency && w.dependency.governor === root
+            && /nsubj/i.test(w.dependency.dependentType))
+            return false;
+    }
+    return true;
+}
+/**
+ * A VOCATIVE (direct address): a noun tagged DISCOURSE/INTJ/DEP and set off by
+ * adjacent punctuation (a comma or "!"), in a clause that is imperative or
+ * subject-less — "Sing, O GODDESS…", "blow, BUGLE, blow".  Conservative: the
+ * noun must be comma/!-adjacent so an ordinary argument noun is not swept in.
+ */
+export function isVocative(word, words) {
+    if (!/^(NN|NNS|NNP|NNPS)$/.test(word.lexicalClass))
+        return false;
+    const role = word.dependency?.dependentType ?? '';
+    if (!/discourse|intj|dep|vocative/i.test(role))
+        return false;
+    const idx = words.indexOf(word);
+    const prev = idx > 0 ? words[idx - 1] : null;
+    const next = idx + 1 < words.length ? words[idx + 1] : null;
+    const commaAdjacent = (prev && /^[,!]$/.test(prev.word)) || (next && /^[,!]$/.test(next.word));
+    return !!commaAdjacent && isImperativeClause(words);
+}

package/dist/stress.d.ts

@@ -1,4 +1,79 @@
 import { ClsWord, IntonationalUnit } from './types.js';
+/** Check if a pair of words forms a left‑stressed compound. */
+export declare function isLeftStressedPair(w1: string, w2: string): boolean;
+/** True if `w2` is a head noun that keeps phrasal/right stress against an N1
+ *  modifier (apple PIE, summer DAY, Fifth AVenue) — the marked right-stress
+ *  exceptions to the otherwise fore-stressing Compound Stress Rule. */
+export declare function isRightStressedHead(w2: string): boolean;
+/**
+ * Direction of primary stress for an adjacent two-word modification structure,
+ * the SINGLE source of truth shared by the lexical compound pass
+ * (`applyCompoundStress`) and the Phrase-Stress phase (`computePhraseStress`),
+ * so the two layers cannot disagree.
+ *
+ *   'left'  = fore-stress, primary on w1 — the Compound Stress Rule default for
+ *             an N+N compound (Chomsky–Halle; McAleese's worked example marks
+ *             ICE cream with primary on "ice", not "cream"): KITCHen table,
+ *             WINdow frame, BEDroom door, plus the curated LEFT_STRESS_* sets.
+ *   'right' = end-stress, primary on w2 — the marked exceptions: food/temporal
+ *             "made of N1" heads (apple PIE, summer DAY), Adj+N which is phrasal
+ *             not compound (sweet CREAM, red CAR), and proper-name sequences
+ *             which carry their own right-headed prosody (New YORK, John SMITH).
+ *   null    = not a compound/modification pair at all.
+ *
+ * The fore-stress default is restricted to COMMON-noun N+N: proper-noun pairs
+ * (NNP/NNPS) are excluded because place- and personal-name sequences are not
+ * reliably fore-stressed, and flipping them would mis-teach New YORK / John SMITH.
+ */
+export declare function compoundStressSide(w1: string, pos1: string, w2: string, pos2: string): 'left' | 'right' | null;
+/** Display-only prefix detection for ALL words (in-vocab AND OOV).
+ *
+ *  The OOV-only `morphologicalStress` prefix path (Tier 1b) only fires when no
+ *  suffix decomposition is found — so "disillusions" (OOV, suffix "-s" → stem
+ *  "disillusion" IN-VOCAB) returns before the prefix path runs, and
+ *  "uneducated" (IN-VOCAB) never hits the OOV branch at all.  Neither gets
+ *  `morphPrefix` set, and the display syllabifier's Maximal Onset principle
+ *  pulls the prefix's final consonant into the next syllable (di·sil·lu·sions,
+ *  u·ne·du·ca·ted).
+ *
+ *  This pass runs AFTER `assignLexicalStress` for every word: if it starts with
+ *  a known productive prefix (from `PREFIX_RULES`) and the stripped stem is in
+ *  the nounsing-pro dictionary, set `word.morphPrefix`.  The syllabifier then
+ *  peels the prefix as the first syllable(s) and syllabifies the stem
+ *  separately, respecting the morpheme boundary (dis·il·lu·sions,
+ *  un·ed·u·ca·ted).  DISPLAY-ONLY — never changes stress or meter.
+ *
+ *  Guards: the stem must carry a primary stress (so we don't peel a prefix off
+ *  a function word like "into"), and the prefix must be at least 2 characters
+ *  (to avoid false positives on short words). */
+export declare function detectDisplayPrefixes(words: ClsWord[]): void;
+/**
+ * Stress Shift — swap primary↔secondary when Nounsing-Pro confirms the word
+ * CAN shift (`suffixShiftPotential` returns `shiftLikely: true`) and the
+ * phonological context motivates it.  This is NOT a global rule — it is
+ * grounded in the dictionary's own shift-likelihood assessment plus a
+ * syntactic/phonological context gate.
+ *
+ * Conditions (ALL must hold):
+ *  1. `suffixShiftPotential(word)` returns `shiftLikely: true`
+ *  2. The word's `stressTrans` has both `1` (primary) and `2` (secondary)
+ *  3. The LAST digit of `stressTrans` is `2` — secondary is on the final
+ *     syllable, so swapping 1↔2 moves primary TO the final
+ *  4. Context gate (either):
+ *     a. The word is a VB at the start of a phonological phrase (imperative
+ *        at phrase start — "REcognize" → "recogNIZE")
+ *     b. Rhythm Rule clash: a stressed syllable follows within 2 syllables
+ *        (the shift avoids a clash with the following stress)
+ *
+ * Words like "realize" (shiftLikely=false) are correctly EXCLUDED —
+ * Nounsing-Pro says they cannot shift, and the code respects that.
+ *
+ * Effect: swap the `lexicalStress` values of the primary (2) and secondary (1)
+ * syllables, so `peakSyllable` and all downstream computation see the shifted
+ * peak.  The syllables' `stress` (raw CMU) values are also swapped for
+ * consistency.
+ */
+export declare function applyStressShift(words: ClsWord[], ius: IntonationalUnit[]): void;
 /**
  * Assign per‑syllable lexical stress to each word in a sentence.
  *
@@ -9,12 +84,16 @@ export declare function assignLexicalStress(words: ClsWord[]): void;
 /**
  * Adjust stresses for nominal compounds.
  *
- * Right‑stressed by default: the second content word keeps primary (2),
- * the first is reduced to secondary (1).
- * Known left‑stressed compounds (material, time, measure, location, self)
- * reverse the pattern.
+ * Fore-stressed by default: an N+N compound puts primary (2) on the first
+ * element, secondary (1) on the second — the Compound Stress Rule (Chomsky–
+ * Halle; McAleese marks ICE cream with primary on "ice", KITCHen table,
+ * WINdow frame).  The marked right-stress exceptions — food/temporal "made of"
+ * heads (apple PIE), Adj+N phrases (sweet CREAM), and proper-name sequences
+ * (New YORK) — reverse it.  All of this lives in `compoundStressSide`.
  */
 export declare function applyCompoundStress(ius: IntonationalUnit[]): void;
+/** Locate the syllable with the highest stress and set it to `value`. */
+export declare function setPrimaryStress(word: ClsWord, value: number): void;
 /**
  * Recursively assign higher stress to content words from right to left.
  * Only the rightmost content word receives a boost (+1 above lexical primary).
@@ -29,4 +108,48 @@ export declare function applyNuclearStress(ius: IntonationalUnit[]): void;
  * information.
  */
 export declare function assignRelativeStresses(words: ClsWord[], ius: IntonationalUnit[]): void;
+/**
+ * Surface-order post-processing passes that re-assert forestress and resolve
+ * residual clashes AFTER the main relativisation.  These run in the Clio engine
+ * inside `assignRelativeStresses`; the Calliope engine calls this separately
+ * after `computeRelativeStress` so the same repairs reach both pipelines.
+ *
+ * The passes are:
+ *   1. resolveCompoundForestress — re-assert left-stress on surface-adjacent
+ *      N+N/J+N compounds the tagger mislabels (WASTE·shore, SEA·shore).
+ *   2. resolveCollocationForestress — forestress lexicalised collocations
+ *      (GOOD old, END-all, OLD days).
+ *   3. resolveHyphenCompounds — resolve dual-strong clashes at hyphen seams
+ *      (torch-flames, blood-red).
+ *   4. resolveLinearClashes — catch residual s-s / m-m / n-n surface clashes
+ *      with the full 7-level demotion cascade (lexical integrity → prominence →
+ *      syntactic headedness → content/function → weight → Rhythm Rule → default).
+ *   5. Exclaimed interjection raise — an interjection immediately followed by
+ *      "!" is lifted one tier ("But—Oh! ye lords…").
+ *
+ * All passes are DEMOTE-ONLY (or forestress re-assertions that raise the LEFT
+ * element of a known compound); none inflate the contour beyond what the lexicon
+ * and phrase-stress rules already established.
+ */
+export declare function applySurfacePostProcessing(words: ClsWord[]): void;
+/**
+ * THE CLASH FILTER — an absolute surface well-formedness constraint.
+ *
+ * On the STRESSED tier {n, m, s} no two *contiguous* syllables may carry the SAME
+ * level: that is a stress clash (two equal prominences with no gradation between
+ * them), which English categorically disallows.  Gradient pairs (sm/ms/sn/ns/mn/nm)
+ * are fine — there is still a step down — as are runs of the unstressed tiers
+ * {w, x} (an unstressed sequence is tolerated, if not ideal).  This generalises
+ * McAleese's Appendix-A step 3d-ii ("stress clashes (ss, ms) > s-s") and Liberman
+ * & Prince's (1977) grid alternation to every level of the strong tier.
+ *
+ * Resolution is DEMOTE-ONLY (never promote — promotion is the meter layer's job,
+ * McAleese Test 2), so the contour is never inflated to break a clash; we iterate
+ * to a fixed point (each change strictly lowers total stress mass, so it
+ * terminates).  Which member yields is decided by `demoteRightOfClash` (grid-based
+ * relative prominence).  Runs on the LINEAR surface order because a clash is a
+ * property of contiguous *pronounced* syllables (Hayes), which a mis-grouped
+ * dependency parse can scatter across phrases.
+ */
+export declare function resolveLinearClashes(words: ClsWord[]): void;
 //# sourceMappingURL=stress.d.ts.map

package/dist/stress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stress.d.ts","sourceRoot":"","sources":["../src/stress.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAyB,gBAAgB,EAAsB,MAAM,YAAY,CAAC;AAujBlG;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CA6Q1D;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAgCjE;AAmBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAyBhE;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CA0GtF"}
+{"version":3,"file":"stress.d.ts","sourceRoot":"","sources":["../src/stress.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAyB,gBAAgB,EAAsB,MAAM,YAAY,CAAC;AA2VlG,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAelE;AAED;;uEAEuE;AACvE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GACjD,MAAM,GAAG,OAAO,GAAG,IAAI,CASzB;AAoMD;;;;;;;;;;;;;;;;;;;iDAmBiD;AACjD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAkB5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CA2EhF;AA+KD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAuR1D;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CA2BjE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYnE;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAwChE;AA8CD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAsLtF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAoBjE;AAyMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAuB3D"}