calliope-ts 0.0.2 → 0.0.3

package/dist/calliope/relstress.js

@@ -0,0 +1,688 @@
+// calliope/relstress.ts — per-phonological-phrase relative stress for Calliope.
+//
+// This is the corrected relativisation McAleese A2 step 1b prescribes —
+// "determine the relative stresses in EACH PP (w / n / m / s)" — and the direct
+// answer to the maintainer's critique of the old pipeline (everything defaulting
+// high, per-word boosts stacking linearly into adjacent reds, function words
+// flattened into long w-runs).
+//
+// Principles:
+//   • Default is LOW.  Each word's prominence is RAISED only with motivation.
+//   • Within a PP there is ONE nuclear peak (s) — the φ's MOST PROMINENT word per the
+//     genuine phrase stress (lowest `phraseStress`, the Compound + Nuclear Stress
+//     Rules computed in bracketing.ts).  Other content words are subordinate (m); the
+//     rest ramp DOWN — nothing is boosted past the peak.
+//   • FUNCTION words take a category gradient, never a flat run:
+//        preposition / article / coordinator / complementiser  → x  (zero-provision)
+//        possessive / personal pronoun / auxiliary / modal      → w  (overt weak)
+//        quantifier / demonstrative / wh-word / negator          → n  (some stress)
+//     so "of all my days" reads x · n · w · s  (of < my < all < days).
+//   • Compound fore-stress (SLATE roof, ICE cream) needs NO special case here: the
+//     Compound Stress Rule already gave the compound's LEFT element the lower
+//     phraseStress, so it wins the φ nuclear automatically.
+//   • The clash invariant is preserved: no two adjacent syllables share n / m / s
+//     (w and x may repeat); the less-prominent of a clashing pair is demoted.
+//
+// This stage DERIVES the symbolic contour FROM the integer phrase stress, per φ — but
+// the two remain SEPARATE material signals: the integer ranking is global (one
+// utterance nuclear), the symbolic contour is local (one beat per φ) and then
+// modified (clash resolution), so they legitimately diverge — never forced equal.
+import { collectPPTokens } from '../phonological.js';
+import { isTransitiveFunctionWord, isPronoun, isInherentlyGiven } from './syntax.js';
+const RANK = { x: 0, w: 1, n: 2, m: 3, s: 4 };
+const LEVELS = ['x', 'w', 'n', 'm', 's'];
+const CONTENT = /^(NN|NNS|NNP|NNPS|JJ|JJR|JJS|VB|VBD|VBG|VBN|VBP|VBZ|RB|RBR|RBS|CD|UH)$/;
+const ARTICLES = new Set(['a', 'an', 'the']);
+const QUANTIFIERS = new Set([
+    'all', 'both', 'each', 'every', 'some', 'any', 'many', 'much', 'few', 'no',
+    'most', 'half', 'several', 'either', 'neither', 'enough',
+]);
+const DEMONSTRATIVES = new Set(['this', 'that', 'these', 'those']);
+// "no" is a NEGATOR, not a reducible determiner: "made with NO loss of time" keeps
+// a beat on "no".  Listed here (ahead of the rel==='DET' → x floor in functionLevel)
+// so the negative determiner is never flattened to the clitic tier.
+const NEGATORS = new Set(['not', 'never', "n't", 'nor', 'no']);
+// "be" reduces in the contour even as a copula ("the sky is BLUE").  "have"/"do"
+// reduce only as AUXILIARIES — as main verbs ("the woods HAVE it", "DO your
+// work") they are full content, so they are gated on the AUX relation below.
+const BE_FORMS = new Set(['be', 'am', 'is', 'are', 'was', 'were', 'been', 'being']);
+// Aphaeresis clitics: "'tis"/"'twas" = it+is / it+was, weak pronoun+copula clipped
+// to a single proclitic syllable — never a stressed content peak (en-pos mis-tags
+// the capitalised "'Tis" as NNP).  Apostrophes already stripped by bare().
+const APHAERESIS = new Set(['tis', 'twas', 'twere', 'twill', 'twould', 'tisnt']);
+function bare(w) {
+    return w.word.toLowerCase().replace(/['’]/g, '');
+}
+function isAphaeresis(w) { return APHAERESIS.has(bare(w)); }
+function isContent(w) {
+    return CONTENT.test(w.lexicalClass) && !isAphaeresis(w);
+}
+function isReducedVerb(w, words) {
+    if (isAphaeresis(w))
+        return true;
+    const rel = w.canonicalRel ?? '';
+    // "to be" (infinitive main verb) and ROOT be-forms ("Where WAS I?",
+    // "I have BEEN") carry a beat — NOT reduced.  Must check BEFORE the AUX
+    // gate because UD maps cop→AUX, so "to be" has canonicalRel='AUX'.
+    if (BE_FORMS.has(bare(w)) && /^(VB|VBD|VBG|VBN|VBP|VBZ)$/.test(w.lexicalClass)) {
+        if (words) {
+            const prev = words
+                .filter(x => x.syllables.length > 0 && x.absoluteIndex < w.absoluteIndex)
+                .sort((a, b) => b.absoluteIndex - a.absoluteIndex)[0];
+            if (prev && (prev.canonicalRel === 'COMPMARK' || prev.lexicalClass === 'TO'))
+                return false;
+        }
+        if (rel === 'ROOT')
+            return false;
+    }
+    if (rel === 'AUX' || rel === 'AUXPASS')
+        return true; // true auxiliary reduces
+    // copular "be" after a function word with a predicate reduces; "have"/"do" as
+    // MAIN verbs do not
+    return BE_FORMS.has(bare(w)) && /^(VB|VBD|VBG|VBN|VBP|VBZ)$/.test(w.lexicalClass);
+}
+/** Intrinsic prominence of a FUNCTION word — the category gradient.  `words` (the
+ *  whole line) lets the transitivity test (Wagner §6.5.5) see a preposition's
+ *  complement: only a COMPLEMENT-TAKING (transitive) preposition has the reduced
+ *  'x' allomorph; a STRANDED or adverbial-particle preposition keeps a beat. */
+function functionLevel(w, words) {
+    const lemma = bare(w);
+    const pos = w.lexicalClass;
+    const rel = w.canonicalRel ?? '';
+    // A quantifier / demonstrative in an ATTRIBUTIVE determiner slot ("each street",
+    // "this cat", "that day") is a reduced determiner (x), NOT a standalone n-tier
+    // quantifier.  Only the determiner USE reduces — a predeterminer ("ALL the",
+    // PDT/det:predet) and a standalone quantifier/demonstrative ("EACH of them",
+    // "THIS is…", rel ≠ det) keep their 'n'.  This is what lets a ϕ-initial
+    // preposition's beat ("through", "in") outrank an interior "each".
+    if (rel === 'DET' && pos !== 'PDT' && !NEGATORS.has(lemma))
+        return 'x';
+    // n — quantifiers, demonstratives, wh-words, negators (carry real stress)
+    if (pos === 'PDT' || QUANTIFIERS.has(lemma) || DEMONSTRATIVES.has(lemma) ||
+        NEGATORS.has(lemma) || /^(WDT|WP|WP\$|WRB)$/.test(pos))
+        return 'n';
+    // "out of" is a compound preposition with fixed stress on "out" (OUT of, not
+    // out OF).  "out" carries the directional content; "of" is the grammatical
+    // linker that floors to 'x'.  Raise "out" to 'n' so it outranks a preceding
+    // unstressed syllable (the "-ter" of "laughter") and differentiates the contour
+    // ("laughter OUT of" → s w n x, not flat s w w x).  Only fires when "of"
+    // immediately follows — a stranded/particle "out" ("coming OUT") is handled by
+    // the transitivity check below and keeps its own beat.
+    if (lemma === 'out') {
+        const next = words.find(x => x.absoluteIndex === w.absoluteIndex + 1);
+        if (next && bare(next) === 'of')
+            return 'n';
+    }
+    // A STRANDED / intransitive preposition ("what are you waiting FOR", "she walked
+    // IN") is NOT the reducible proclitic of "in the house" — Wagner §6.5.5: only
+    // transitive functors have the weak allomorph.  It keeps an overt beat ('w'), so
+    // the metrical fitter can promote it; a TRANSITIVE preposition floors at 'x'.
+    if (pos === 'IN' || pos === 'TO' || rel === 'CASE') {
+        return isTransitiveFunctionWord(w, words) ? 'x' : 'w';
+    }
+    // x — pure clitics: articles, coordinators, complementisers
+    if (ARTICLES.has(lemma) || pos === 'CC' || rel === 'CC' || rel === 'COMPMARK')
+        return 'x';
+    // w — possessives, pronouns, auxiliaries, modals, leftover determiners
+    return 'w';
+}
+/** The peak (highest lexical-stress) syllable of a word. */
+function peakSyllable(w) {
+    let best = null;
+    let bestV = -1;
+    for (const s of w.syllables) {
+        const v = s.lexicalStress ?? s.stress;
+        if (v > bestV) {
+            bestV = v;
+            best = s;
+        }
+    }
+    return best;
+}
+/** Paint every syllable of a word given the level assigned to its peak.
+ *
+ *  The within-word contour preserves the LEXICAL gradient primary > secondary >
+ *  unstressed (Nounsing's CMU stress → lexicalStress 2 = primary, 1 = secondary,
+ *  0 = unstressed).  Crucially a SECONDARY stress is a REAL stress and must land
+ *  STRICTLY ABOVE this word's own unstressed floor — never collapsed flat onto it.
+ *  Hayes' stress-maximum theory: a polysyllable's internal contour (which syllables
+ *  bear primary, secondary, or no stress) is a fixed lexical fact, not a position to
+ *  be overwritten — "ac·CEL·er·AT·ed" must keep its EY2 secondary distinct from the
+ *  truly toneless syllables around it, in a non-nuclear word (peak = m) exactly as
+ *  much as in a nuclear one.
+ *  peak → level; a co-primary (another lexicalStress-2 syllable) sits just below the
+ *  peak; a secondary (lexicalStress 1) sits ONE TIER ABOVE this word's floor — 'n' if
+ *  the floor is 'w' (a content word: ti in for·TI·tude is 'w', so tude's secondary
+ *  clears it at 'n'), or 'w' if the floor is 'x' (a reduced function word: der in
+ *  UNDER·neath is 'x', so un's secondary clears it at 'w', not flattened to 'x') —
+ *  capped below the peak and at 'n' (the canonical non-peak ceiling); unstressed
+ *  syllables sit AT the floor. */
+function paintWord(w, level) {
+    const peak = peakSyllable(w);
+    const peakRank = RANK[level];
+    const floorRank = w.isContent ? RANK.w : RANK.x; // unstressed floor for this word
+    for (const s of w.syllables) {
+        if (s === peak) {
+            s.relativeStress = level;
+            continue;
+        }
+        const lv = s.lexicalStress ?? s.stress;
+        let r;
+        if (lv >= 2) {
+            r = peakRank - 1; // co-primary: just below the peak
+        }
+        else if (lv === 1) {
+            // SECONDARY stress → one tier ABOVE this word's floor (never flattened onto
+            // it), never reaching the peak, never exceeding 'n'.
+            r = Math.min(floorRank + 1, peakRank - 1, RANK.n);
+        }
+        else {
+            r = Math.min(floorRank, peakRank); // unstressed (≤ peak for reduced words)
+        }
+        s.relativeStress = LEVELS[Math.max(0, Math.min(r, peakRank))];
+    }
+}
+/** Relativise one phonological phrase by READING the genuine phrase stress.
+ *
+ *  The cyclic Compound + Nuclear Stress Rules (bracketing.ts) already ranked every
+ *  word with an integer (1 = strongest).  Within a φ:
+ *    • the lowest-ranked content word is the NUCLEAR (s) — and because the Compound
+ *      Stress Rule fore-stressed a compound's LEFT element (lower integer), the
+ *      compound peak falls out here for free (SLATE roof, ICE cream);
+ *    • every other content word is a SECONDARY BEAT (m) — kept flat, NOT ramped to a
+ *      trough, so the alternating beats that metrical verse needs stay visible (a
+ *      ramp here flattened Hiawatha's "shores"/"Gitche" into non-beats → mis-meter);
+ *    • the FINE gradient the maintainer asked for (ICE > cream, not a flat tie) is
+ *      produced where content ABUTS, by clash resolution that breaks the tie with the
+ *      phrase-stress integer — the less-prominent (higher-integer) member of two
+ *      adjacent beats is the one demoted (so ICE ps2 keeps the beat, cream ps3 drops).
+ *
+ *  Two anchored beats per φ, per Kiparsky's "beginnings free, endings strict"
+ *  (McAleese pp.34–35, Hayes & Kaun 1996 — the procedure reads the stresses at the
+ *  END of each unit, but the LEFT edge carries a lighter beat too):
+ *    • ENDING (strict): the rightmost lowest-ranked content word → the nuclear s.
+ *    • BEGINNING (free, light): a φ-initial PREPOSITION rises x→w — the subtle
+ *      left-edge beat the maintainer hears on "…working | IN the house" and that lets
+ *      "…through | each…" read through(w) > each(x).  Articles, pronouns, auxiliaries
+ *      and coordinators do not rise. */
+function relativisePP(toks, words) {
+    if (toks.length === 0)
+        return;
+    // A DISCOURSE-GIVEN content word (repeated from an earlier line of the stanza) is
+    // subordinated relative to its sister (Wagner Ch.7) — but only as an ANCHOR
+    // demotion, and never when it would empty the φ of content.  A word given a higher
+    // (worse) effective phrase-stress is less likely to win the φ nuclear.
+    const ps = (w) => {
+        const base = w.phraseStress || Infinity;
+        // A given content word — discourse-given (repeated from an earlier line), an
+        // inherently-given indefinite pronoun ("something", Wagner §7.2.3), or
+        // anaphorically given via a shared-head coordinate structure ("young blood
+        // and high blood" → the second "blood") — is less likely to win the φ
+        // nuclear, so a heavier sister in the SAME φ takes the beat.
+        const given = isContent(w) && (w.discourseGiven || isInherentlyGiven(w) || w.coordinateGiven);
+        return given ? base + 2 : base;
+    };
+    // Pronoun promotion (Nuclear Stress Rule + trochaic inversion): a simple personal
+    // pronoun (PRP with no apostrophe) at the start of the φ gets promoted to an
+    // anchor if it is syntactically prominent (phraseStress === 1) and its following
+    // verb in the φ is a function/light verb (have, has, had, do, etc.) with weaker
+    // phraseStress (phraseStress > 1).  This captures the trochaic inversion in
+    // "I have no right" (I=1, have=3 → I wins the beat, have reduces) while
+    // sparing contractions ("I'll", "I'm") and pronouns preceding lexical content
+    // verbs ("I would give" → give is lexical, so I does NOT promote).
+    const promotePronoun = (w) => {
+        if (w.lexicalClass !== 'PRP' || w.word.includes("'") || w.word.includes("’"))
+            return false;
+        if (w.phraseStress !== 1)
+            return false;
+        const idx = toks.indexOf(w);
+        if (idx !== 0)
+            return false;
+        const nextVerb = toks.slice(1).find(x => /^VB/.test(x.lexicalClass));
+        if (!nextVerb)
+            return false;
+        const FUNCTION_VERBS_SHORT = new Set(['have', 'has', 'had', 'do', 'does', 'did', 'get', 'got']);
+        if (!FUNCTION_VERBS_SHORT.has(nextVerb.word.toLowerCase()))
+            return false;
+        // Only the MAIN-verb use of have/do ("I HAVE no right" — possession) licenses
+        // the inversion.  As an AUXILIARY ("i have SENE them") the beat belongs to the
+        // lexical verb further right; promoting the pronoun here handed it the φ
+        // nuclear over the participle ("I"(s) have sene(m) — the Wyatt L3 bug).
+        if ((nextVerb.canonicalRel ?? '') === 'AUX' || (nextVerb.canonicalRel ?? '') === 'AUXPASS')
+            return false;
+        if ((nextVerb.phraseStress || 0) > 1)
+            return true;
+        return false;
+    };
+    // The set the gradient is measured against: content words (non-reduced) first;
+    // for a content-less φ fall back to its prominent function words ("for THAT",
+    // "to YOU"), then to any content, then to anything — so every φ has an anchor.
+    let anchors = toks.filter(w => promotePronoun(w) || (isContent(w) && !isReducedVerb(w, words)));
+    if (anchors.length === 0)
+        anchors = toks.filter(w => !isReducedVerb(w, words) && functionLevel(w, words) !== 'x');
+    if (anchors.length === 0)
+        anchors = toks.filter(isContent);
+    if (anchors.length === 0)
+        anchors = toks.slice();
+    const anchorSet = new Set(anchors);
+    // Nuclear strength = the lowest phrase-stress integer among the anchors; the
+    // nuclear WORD is the RIGHTMOST anchor at that value (English resolves rightward
+    // toward the nuclear).  Because the Compound Stress Rule already fore-stressed a
+    // compound's LEFT element (lower integer), the compound peak falls out here for
+    // free — SLATE roof, ICE cream — with no special case.
+    const localMin = Math.min(...anchors.map(ps));
+    let nuclear = null;
+    for (const w of anchors)
+        if (ps(w) === localMin)
+            nuclear = w; // last = rightmost
+    // Base level per token.
+    const levels = toks.map((w) => {
+        if (w === nuclear)
+            return 's'; // φ nuclear (right edge)
+        if (anchorSet.has(w))
+            return 'm'; // secondary beat (flat — the
+        //                                  gradient among abutting beats is set by clash resolution)
+        // BE-FORM flooring — only fires for true AUX copulas now (isReducedVerb
+        // already excludes "to be" and ROOT be-forms, which are anchors with beats).
+        // 'x' reserved for the clearest copula+predicate case: be-form after a
+        // function word directly followed by an adjective/noun predicate.
+        // Everything else → 'w' (promotable).
+        if (isReducedVerb(w, words)) {
+            if (BE_FORMS.has(bare(w))) {
+                const i = toks.indexOf(w);
+                const prev = i > 0 ? toks[i - 1] : null;
+                const followingContent = toks.slice(i + 1).find(x => isContent(x));
+                if (prev && !isContent(prev) && followingContent &&
+                    /^(JJ|NN)/.test(followingContent.lexicalClass))
+                    return 'x';
+            }
+            return 'w';
+        }
+        // Function word → its category gradient; a POLYSYLLABIC one floors its peak at
+        // 'w' so its stressed syllable outranks the reduced one (be·CAUSE, u·PON).
+        let tier = functionLevel(w, words);
+        if (w.syllables.length > 1 && tier === 'x')
+            tier = 'w';
+        // A polysyllabic function word whose lexicon entry records a genuine PRIMARY
+        // stress ("O·ver", "AF·ter", "UN·der", "u·PON") is not a reduced clitic — its
+        // stressed syllable is a real (if light) beat that metrical verse freely uses
+        // ("O·ver many a quaint and curious volume…" opens The Raven's trochee chain).
+        // Raise the peak one tier to 'n' — still below every content beat, still
+        // promotable/demotable by the fitter — leaving true reduced polysyllables
+        // ("be·cause" 00, "where·fore" secondary-only) at 'w'.
+        if (w.syllables.length > 1 && tier === 'w' &&
+            w.syllables.some(s => (s.lexicalStress ?? s.stress) === 2)) {
+            tier = 'n';
+        }
+        return tier;
+    });
+    // Phrase-initial beat ("beginnings free" — a light left-edge beat): a φ-initial
+    // PREPOSITION rises x→w (the subtle beat on "IN the house"; lets "through" outrank
+    // an interior "each"), unless it is itself the nuclear.  Also fires for the first
+    // IN/TO AFTER a coordinator at the φ's start ("And of the best" — "And" is toks[0]
+    // at 'x', "of" is toks[1]; "of" gets the raise so it reads 'w', not flat 'x').
+    const raiseFirstPrep = (idx) => {
+        if (idx < 0 || idx >= toks.length)
+            return;
+        const w = toks[idx];
+        if (w === nuclear)
+            return;
+        if ((w.lexicalClass === 'IN' || w.lexicalClass === 'TO') && levels[idx] === 'x') {
+            levels[idx] = 'w';
+        }
+    };
+    raiseFirstPrep(0);
+    // If toks[0] is a coordinator (CC), the first IN/TO after it also gets the raise
+    // — it is κ-initial (the start of the prepositional phrase after "and"), even if
+    // not ϕ-initial.  "And of the best" → "of" rises to 'w'.
+    if (toks.length > 1 && (toks[0].lexicalClass === 'CC' || (toks[0].canonicalRel ?? '') === 'CC')) {
+        for (let i = 1; i < toks.length; i++) {
+            if (toks[i].lexicalClass === 'IN' || toks[i].lexicalClass === 'TO') {
+                raiseFirstPrep(i);
+                break;
+            }
+            // Skip over articles/determiners to find the first IN/TO
+            if (toks[i].isContent)
+                break; // hit content before any prep
+        }
+    }
+    // Givenness escape (Wagner §6.1.3, maintainer's no-flat-run-on directive): when a
+    // φ's nuclear is an inherently-given PRONOUN immediately preceded by a transitive
+    // PREPOSITION ("of HIM", "to THEE"), do NOT leave them on a par or stress the
+    // pronoun — subordinate the given pronoun and give the preposition the beat
+    // ("OF him"), the differentiated reading.  The metrical fitter may re-promote the
+    // pronoun if the line demands it.
+    if (nuclear && isPronoun(nuclear)) {
+        const ni = toks.indexOf(nuclear);
+        const prep = ni > 0 ? toks[ni - 1] : null;
+        if (prep && (prep.lexicalClass === 'IN' || prep.lexicalClass === 'TO' ||
+            (prep.canonicalRel ?? '') === 'CASE')) {
+            const pi = toks.indexOf(prep);
+            levels[ni] = 'w'; // given pronoun subordinated
+            levels[pi] = 'n'; // preposition takes the differentiating beat
+        }
+    }
+    toks.forEach((w, i) => paintWord(w, levels[i]));
+    // NOTE: the clash invariant (no adjacent equal n/m/s) is enforced once, globally,
+    // by resolveStressClashes over TRUE adjacent syllables in computeRelativeStress —
+    // not here.  A per-word peak comparison would wrongly treat two polysyllables'
+    // stressed syllables as adjacent ("TY·ger TY·ger", peaks two syllables apart) and
+    // spuriously flatten every falling trochaic/dactylic foot.
+}
+const CLASH_NOUN = /^(NN|NNS|NNP|NNPS)$/;
+/** Two clashing words form a COMPOUND whose LEFT element fore-stresses (Compound
+ *  Stress Rule): a NOMD modifier + its head, or two adjacent nouns (the N+N compound
+ *  the tagger routinely mislabels).  Only for such a pair does the clash keep the
+ *  lower-phraseStress (fore-stressed) member; every OTHER clash uses the default
+ *  rightward resolution.  This is the narrow place the Compound Stress Rule needs to
+ *  reach the contour when neither element is the φ nuclear (e.g. "ice cream" buried
+ *  under a wrong root) — without disturbing ordinary verse, where forcing the
+ *  lower-phraseStress member to win moved beats onto odd positions and mis-metered. */
+function isCompoundPair(a, b) {
+    if (a === b)
+        return false;
+    if ((a.canonicalRel ?? '') === 'NOMD' && a.dependency?.governor === b)
+        return true;
+    if ((b.canonicalRel ?? '') === 'NOMD' && b.dependency?.governor === a)
+        return true;
+    return CLASH_NOUN.test(a.lexicalClass) && CLASH_NOUN.test(b.lexicalClass) &&
+        Math.abs(a.absoluteIndex - b.absoluteIndex) === 1;
+}
+/**
+ * Stress-clash resolution over the TRUE surface syllable sequence (McAleese A2
+ * step 3d.ii: "stress clashes (ss, ms) > s-s").  A BEAT is one per foot (at most
+ * one per phonological phrase) — so two ADJACENT strong syllables (both ≥ m, in
+ * any order: ss, ms, sm, mm) are a clash, NOT two beats.  One member drops to 'n'
+ * (below the beat threshold), leaving a single beat with a demoted neighbour;
+ * adjacent equal 'n' likewise demotes one member to 'w'.
+ *
+ * WHICH member drops:
+ *   • a COMPOUND pair (isCompoundPair) keeps the fore-stressed (lower-phraseStress)
+ *     element and demotes the other — the Compound Stress Rule, "ICE cream";
+ *   • an n-n tie is broken by LEXICAL stress (Hayes' stress-maximum principle):
+ *     the syllable with the higher lexicalStress value (2=primary > 1=secondary
+ *     > 0=unstressed) is protected; the lower yields to 'w'.  This preserves a
+ *     polysyllable's internal contour — a PRIMARY (lexicalStress 2) that was
+ *     demoted to 'n' by a prior m/s clash still outranks a SECONDARY
+ *     (lexicalStress 1), which in turn outranks an artifact 'n' (lexicalStress
+ *     0, reached via the function-word gradient or a prior demotion).  Without
+ *     this, a cascade can crush real lexical data — e.g. "before" (be=1, fore=2):
+ *     "fore" loses an m/s clash (demoted to 'n'), then ties "be"(n) and was
+ *     wrongly sacrificed (the old code only protected ===1 secondaries, treating
+ *     the primary 2 as "not grounded"), corrupting "wn" into "nw".  Equal-
+ *     lexical-stress ties (both primary, both secondary, both unstressed) default
+ *     left (Rhythm Rule);
+ *   • every other clash demotes the lower symbolic level, ties to the LEFT (the
+ *     Rhythm Rule / Iambic Reversal — an earlier stress backs off ahead of one that
+ *     follows closely, not a general "endings are strict" license).
+ *
+ * Because it compares adjacent SYLLABLES (not word peaks), a falling foot whose
+ * stresses are separated by a weak syllable ("TY·ger TY·ger", "HARB·our") is left
+ * intact — only genuinely abutting beats collapse.
+ */
+function resolveStressClashes(words, sylWord) {
+    const syls = [];
+    for (const w of [...words].sort((a, b) => a.absoluteIndex - b.absoluteIndex)) {
+        for (const s of w.syllables)
+            syls.push(s);
+    }
+    // Lexical stress value of a syllable (2=primary, 1=secondary, 0=unstressed).
+    // Used to break n-n ties: a syllable with HIGHER lexical stress has greater
+    // phonological integrity (Hayes' stress-maximum principle) and is protected
+    // against demotion by a syllable with lower lexical stress.  The prior code
+    // checked only ===1 (secondary), which inverted the hierarchy — a primary
+    // (lexicalStress===2) was treated as "not grounded" and sacrificed to a
+    // secondary, corrupting words like "before" (be=1/secondary, fore=2/primary)
+    // into "nw" instead of "wn".
+    const lexVal = (s) => s.lexicalStress ?? s.stress ?? 0;
+    let changed = true;
+    for (let guard = 0; changed && guard < 8; guard++) {
+        changed = false;
+        for (let i = 0; i + 1 < syls.length; i++) {
+            const a = syls[i], b = syls[i + 1];
+            const ra = RANK[a.relativeStress ?? 'w'];
+            const rb = RANK[b.relativeStress ?? 'w'];
+            if (ra >= RANK.m && rb >= RANK.m) {
+                const wa = sylWord.get(a), wb = sylWord.get(b);
+                let demoteA;
+                if (wa && wb && wa !== wb && isCompoundPair(wa, wb)) {
+                    // compound fore-stress: demote the LESS prominent (higher phrase stress)
+                    demoteA = (wa.phraseStress || Infinity) >= (wb.phraseStress || Infinity);
+                }
+                else {
+                    demoteA = ra <= rb; // default: lower level, tie → left
+                }
+                if (demoteA)
+                    a.relativeStress = 'n';
+                else
+                    b.relativeStress = 'n';
+                changed = true;
+            }
+            else if (ra === RANK.n && rb === RANK.n) {
+                // Break the tie by LEXICAL stress: the syllable with higher lexical
+                // stress (primary > secondary > unstressed) is protected; the lower
+                // yields.  This preserves a polysyllable's internal contour (the
+                // primary survives even if a prior clash demoted it to n) while still
+                // letting genuine secondaries (lexicalStress 1) beat artifact n's
+                // (lexicalStress 0, reached via function-word gradient or prior
+                // demotion).  Equal-lexical-stress ties default left (Rhythm Rule).
+                const la = lexVal(a), lb = lexVal(b);
+                if (la > lb)
+                    b.relativeStress = 'w';
+                else if (lb > la)
+                    a.relativeStress = 'w';
+                else
+                    a.relativeStress = 'w'; // tie → default left
+                changed = true;
+            }
+        }
+    }
+}
+/** Inherent-givenness nuclear demotion (Wagner §7.2.3).  After each φ has been
+ *  relativised, an inherently-given indefinite pronoun that won its OWN φ's nuclear
+ *  (e.g. a lone "Something" set off as its own ϕ) should still YIELD the utterance
+ *  peak to a heavier element later in the same intonational unit — so when a LATER
+ *  word in the IU also reaches 's', the given pronoun's peak is demoted s→m.  It
+ *  keeps a beat (its lexical contour is untouched below the peak) but no longer
+ *  claims the main prominence: "Something(m) for the modern STAGE(s)".
+ *
+ *  Guards keep it from crushing a FOCAL pronoun: it never fires when the given word
+ *  is the IU's only nuclear (a lone "Something."), and skips a lemma repeated in the
+ *  IU (focal anaphora). */
+function demoteGivenNuclei(iuWords) {
+    const ordered = iuWords.filter(w => w.syllables.length > 0)
+        .sort((a, b) => a.absoluteIndex - b.absoluteIndex);
+    const peak = (w) => Math.max(0, ...w.syllables.map(s => RANK[s.relativeStress ?? 'w']));
+    for (let i = 0; i < ordered.length; i++) {
+        const w = ordered[i];
+        if (!isInherentlyGiven(w) || peak(w) !== RANK.s)
+            continue;
+        const lemma = bare(w);
+        if (ordered.filter(x => bare(x) === lemma).length > 1)
+            continue; // focal repetition
+        if (!ordered.slice(i + 1).some(x => peak(x) === RANK.s))
+            continue; // no heavier later nuclear
+        for (const s of w.syllables)
+            if ((s.relativeStress ?? 'w') === 's')
+                s.relativeStress = 'm';
+    }
+}
+/** Alternation promotion (Attridge 1982), gated by Hayes' stress-maximum
+ *  monosyllable/polysyllable asymmetry (McAleese pp.49-57; Halle-Keyser, Kiparsky
+ *  1975): English does not sustain a trough of three-or-more weak syllables — its
+ *  medial syllable is promoted to a light beat, McAleese's 'n' ("some stress"). This
+ *  is the SAME promotion the meter-fitter applies internally (`scansion.ts`: a 'w'
+ *  flanked by weakness realises a beat); writing it into the displayed contour
+ *  breaks the long w-troughs the maintainer flagged.
+ *
+ *  NOTE on grounding: "beginnings free, endings strict" (Kiparsky 1968) is a loose
+ *  statistical tendency about WHERE stress clashes resolve in the line, not a
+ *  license to promote by position alone — it says nothing about whether a given
+ *  syllable is phonologically eligible to carry stress at all.  The actual gate
+ *  here is Hayes' stress-maximum asymmetry: a STRESSED MONOSYLLABLE is positionally
+ *  free (it has no internal contour to violate, so context can promote it — "error
+ *  AND upon", "not TO advance"), but an UNSTRESSED syllable inside a POLYSYLLABLE
+ *  is not free — the lexicon's verdict that it carries no stress (lexicalStress
+ *  === 0) is a fixed phonological fact, and promoting it fabricates a secondary
+ *  stress Nounsing-Pro never recorded (e.g. promoting "mariner"'s toneless "-ner"
+ *  just because it sits between two other weak syllables, one of which belongs to
+ *  the unrelated following word).  So:
+ *   • only an overt-weak 'w' promotes; a reduced clitic 'x' (the/a/of) stays the
+ *     genuine trough — a clitic is never a beat;
+ *   • a candidate that is the toneless (lexicalStress === 0) syllable of a word with
+ *     MORE THAN ONE syllable is excluded — its own word's lexical contour already
+ *     settled the question, and position cannot overrule it; a true monosyllable, or
+ *     a syllable that itself carries some lexical stress (primary or secondary) but
+ *     is sitting low because its WHOLE WORD only earned a low φ-level, remains
+ *     eligible;
+ *   • it must sit between two weak (w/x) syllables — the interior of a real trough;
+ *   • the LINE EDGES do not count as weak, so a line-initial/final weak is never
+ *     promoted (the off-beat before the first beat, and the final cadence, are left);
+ *   • promotions never abut (a promoted 'n' breaks the run), so the result alternates
+ *     w·n·w and the clash invariant (no adjacent equal n) is preserved. */
+function promoteWeakTroughs(words) {
+    const syls = [];
+    const sylWord = new Map();
+    for (const w of [...words].sort((a, b) => a.absoluteIndex - b.absoluteIndex)) {
+        for (const s of w.syllables) {
+            syls.push(s);
+            sylWord.set(s, w);
+        }
+    }
+    const isW = (i) => i >= 0 && i < syls.length && syls[i].relativeStress === 'w';
+    const isLexicallyToneless = (i) => {
+        const s = syls[i];
+        if ((s.lexicalStress ?? s.stress) !== 0)
+            return false; // carries some real stress
+        const w = sylWord.get(s);
+        return !!w && w.syllables.length > 1; // interior of a polysyllable
+    };
+    let lastProm = -2;
+    for (let i = 1; i < syls.length - 1; i++) {
+        if (!isW(i) || !isW(i - 1) || !isW(i + 1))
+            continue; // medial of a ≥3 literal-w run
+        if (isLexicallyToneless(i))
+            continue; // no fabricated secondaries
+        if (i - 1 === lastProm)
+            continue; // keep promotions non-adjacent
+        syls[i].relativeStress = 'n';
+        lastProm = i;
+    }
+}
+/** Lower a polysyllabic word's final 'w' syllable to 'x' when another 'w'
+ *  immediately follows it in surface order.  The unstressed ending of a longer
+ *  word (even a stress-bearing word) carries fainter emphasis than even a weakly-
+ *  stressed syllable or word immediately following it — so a w-w seam at a word
+ *  boundary is differentiated by dropping the word-internal one to the clitic tier.
+ *
+ *  Narrowly scoped: only fires on the FINAL syllable of a polysyllabic word (2+
+ *  syllables) that is 'w' (not 'n', 'm', 's', or 'x'), AND only when the very next
+ *  syllable in surface order is also 'w'.  Does NOT affect any other syllable of
+ *  the word, does NOT fire when the next syllable is 'x', 'n', 'm', or 's'. */
+function demotePolysyllabicFinalTrough(words) {
+    const syls = [];
+    const sylWord = new Map();
+    for (const w of [...words].sort((a, b) => a.absoluteIndex - b.absoluteIndex)) {
+        for (const s of w.syllables) {
+            syls.push(s);
+            sylWord.set(s, w);
+        }
+    }
+    for (let i = 0; i < syls.length - 1; i++) {
+        const s = syls[i];
+        const next = syls[i + 1];
+        if (s.relativeStress !== 'w')
+            continue;
+        if (next.relativeStress !== 'w')
+            continue;
+        const w = sylWord.get(s);
+        if (!w || w.syllables.length < 2)
+            continue; // polysyllabic only
+        if (s !== w.syllables[w.syllables.length - 1])
+            continue; // final syllable only
+        s.relativeStress = 'x';
+    }
+}
+/** Anaphoric givenness in coordinate structures (Krifka §4, Wagner §7.2).
+ *  In a coordinate structure "X blood and Y blood" the HEAD lemma ("blood") is
+ *  repeated across conjuncts.  Both occurrences are the shared contrastive
+ *  background — the CATEGORY "blood" is what stays constant, and the modifiers
+ *  ("Young", "high") carry the contrastive focus.  So BOTH heads are demoted
+ *  (`coordinateGiven`), letting the modifier win the φ nuclear in EACH conjunct
+ *  ("YOUNG blood and HIGH blood").  This is distinct from a refrain (identical
+ *  phrase repeated for emphasis = focal) and from cross-line discourse
+ *  givenness (repetition across lines of a stanza).
+ *
+ *  Detection: a content word whose `canonicalRel` is CONJ and whose governor
+ *  shares the same lemma.  BOTH the conjunct (second occurrence) AND its
+ *  governor (first occurrence) are marked `coordinateGiven`.  The relativiser's
+ *  `ps()` then demotes both, so the modifier in each φ wins the beat.
+ *
+ *  Guard: only fires when the conjuncts' modifiers DIFFER — if the entire phrase
+ *  is identical ("nevermore and nevermore") it's a refrain, not a shared-head
+ *  coordinate, and both occurrences stay focal. */
+function markCoordinateGivenness(words) {
+    for (const w of words) {
+        if (!isContent(w) || (w.canonicalRel ?? '') !== 'CONJ')
+            continue;
+        const gov = w.dependency?.governor;
+        if (!gov || gov === w)
+            continue;
+        // Same lemma (head repeated across conjuncts)?
+        if (bare(w) !== bare(gov))
+            continue;
+        // Guard against a refrain: check that the conjuncts have DIFFERENT
+        // pre-head modifiers.  Compare the AMOD/ADVMOD lemmas immediately before
+        // each head.  If both heads have the same modifier (or neither has one),
+        // leave both focal — it's either a refrain or a plain coordination.
+        const modBefore = (head) => {
+            const idx = words.indexOf(head);
+            if (idx <= 0)
+                return '';
+            const prev = words[idx - 1];
+            if ((prev.canonicalRel ?? '') === 'AMOD' || (prev.canonicalRel ?? '') === 'ADVMOD')
+                return bare(prev);
+            return '';
+        };
+        if (modBefore(w) === modBefore(gov))
+            continue;
+        // Mark BOTH heads as coordinate-given: the shared head is the contrastive
+        // background in both conjuncts, so contrastive focus falls on BOTH modifiers.
+        w.coordinateGiven = true;
+        gov.coordinateGiven = true;
+    }
+}
+/** Assign relative stress for the whole sentence, one PP at a time. */
+export function computeRelativeStress(words, ius) {
+    // Mark anaphorically-given heads in coordinate structures before relativisation,
+    // so the relativiser's `ps()` can demote them and let the modifier win the beat.
+    markCoordinateGivenness(words);
+    for (const iu of ius) {
+        for (const pp of iu.phonologicalPhrases) {
+            const toks = collectPPTokens(pp)
+                .filter(w => w.syllables.length > 0)
+                .sort((a, b) => a.absoluteIndex - b.absoluteIndex);
+            relativisePP(toks, words);
+        }
+    }
+    // Enforce the clash rule over the whole line's surface syllables (catches the
+    // cross-PP abutments the per-PP painting cannot see).  Carry each syllable's word
+    // so the clash can recognise a compound pair and apply the Compound Stress Rule.
+    const sylWord = new Map();
+    for (const w of words)
+        for (const s of w.syllables)
+            sylWord.set(s, w);
+    resolveStressClashes(words, sylWord);
+    // Per-IU: an inherently-given indefinite pronoun yields its φ-nuclear to a heavier
+    // later element in the same IU (after clash resolution, so the demotion is final).
+    for (const iu of ius) {
+        const iuWords = iu.phonologicalPhrases.flatMap(pp => collectPPTokens(pp));
+        demoteGivenNuclei(iuWords);
+    }
+    // Final readability pass: promote the medial weak of a ≥3-weak trough to 'n'
+    // (Attridge alternation), breaking long w-runs and filling promotable beats.
+    promoteWeakTroughs(words);
+    // Differentiate w-w seams at polysyllabic word boundaries: lower a
+    // polysyllabic word's final 'w' to 'x' when another 'w' immediately follows.
+    demotePolysyllabicFinalTrough(words);
+}