calliope-ts 0.0.2 → 0.0.3

package/src/calliope/feats.ts

@@ -0,0 +1,46 @@
+// calliope/feats.ts — parse UD morphological FEATS onto ClsWord (Phase 1 enabler).
+//
+// The parser stores the raw FEATS string ("Number=Sing|Person=3|Tense=Pres|
+// VerbForm=Fin") on `word.lexicalDetails`, but no downstream module could read it:
+// `udpos.ts:feat()` only sees the UDPipe-level `UDWord.featsMap` at parse time.  This
+// pass parses `lexicalDetails` into `word.featsMap` ONCE, early in the Calliope
+// pipeline, so the stress / bracketing / relativiser modules can key on morphology
+// (VerbForm=Part → participle, Voice=Pass → underlying object subject, PronType=Prs →
+// inherently given, Degree=Cmp → JJR, …).  Pure plumbing — it mutates only the
+// additive `featsMap`, never the parse.
+
+import { ClsSentence, ClsWord } from '../types.js';
+
+/** Parse a UD FEATS string ("A=b|C=d") into a key→value record. */
+function parseFeatsString(raw: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const pair of raw.split('|')) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) continue;
+    const k = pair.slice(0, eq).trim();
+    const v = pair.slice(eq + 1).trim();
+    if (k && v) out[k] = v;
+  }
+  return out;
+}
+
+/** Populate `word.featsMap` for every word in the sentence from `lexicalDetails`. */
+export function parseFeats(sent: ClsSentence): void {
+  for (const w of sent.words) {
+    if (w.featsMap) continue;                // already parsed (idempotent)
+    w.featsMap = parseFeatsString(w.lexicalDetails);
+  }
+}
+
+/** Read one morphological feature, undefined if absent.  Lazily parses on demand
+ *  so callers reached before `parseFeats` still work. */
+export function feat(w: ClsWord, key: string): string | undefined {
+  if (!w.featsMap) w.featsMap = parseFeatsString(w.lexicalDetails);
+  return w.featsMap[key];
+}
+
+/** True when a feature has the given value. */
+export function featIs(w: ClsWord, key: string, value: string): boolean {
+  return feat(w, key) === value;
+}

package/src/calliope/names.ts

@@ -0,0 +1,44 @@
+// calliope/names.ts — proper-NOUN (person) vs proper-NAME (place) typing via the
+// `humannames` and `cities-list` membership lists.  These packages are JUST lists
+// ({ "John": 1, … }), so this is a boolean enrichment, not a pipeline: it flags a
+// token as a known person and/or place name to drive Scenario C (proper-name
+// head-stress) and EXT.
+//
+// Lookups are GATED to proper-noun-tagged tokens (NNP/NNPS).  Both lists are huge
+// (197k names, 79k cities) and overlap heavily with common words — "Will", "May",
+// "Rose", "Sun", "York", "Reading" are all in them — so flagging an untyped token
+// would be noise.  Restricting to NNP(S) keeps the signal honest.
+
+import { createRequire } from 'module';
+import { ClsSentence } from '../types.js';
+
+const req = createRequire(import.meta.url);
+
+function loadList(pkg: string): Record<string, number> {
+  try {
+    const m = req(pkg);
+    return (m && typeof m === 'object' ? m : {}) as Record<string, number>;
+  } catch {
+    return {};
+  }
+}
+
+export const PERSON = loadList('humannames');
+export const PLACE = loadList('cities-list');
+const PROPER = /^(NNP|NNPS)$/;
+
+export function inList(list: Record<string, number>, surface: string): boolean {
+  const key = surface.replace(/['’].*$/, '').replace(/[^A-Za-z-]/g, '');
+  if (!key) return false;
+  const cap = key[0].toUpperCase() + key.slice(1);
+  return !!(list[key] || list[cap]);
+}
+
+/** Flag proper-noun tokens as person and/or place names (membership only). */
+export function tagNames(sent: ClsSentence): void {
+  for (const w of sent.words) {
+    if (!PROPER.test(w.lexicalClass)) continue;
+    if (inList(PERSON, w.word)) w.isPersonName = true;
+    if (inList(PLACE, w.word)) w.isPlaceName = true;
+  }
+}

package/src/calliope/postag.ts

@@ -0,0 +1,253 @@
+// calliope/postag.ts — Calliope-only POS correction via en-lexicon.
+//
+// THE BUG THIS FIXES: en-pos tags a capitalised line-initial common word as a
+// proper noun ("Pale rain" → Pale/NNP, "High tide" → High/NNP), purely from the
+// capital.  That mis-tag flips content class, derails the dependency parse, and —
+// once relation-keyed stress is reintroduced — fore-stresses an adjective.
+//
+// en-lexicon (a CORE FinNLP module, the POS dictionary that en-pos/en-parse are
+// built on) carries the true multi-role reading keyed on the LOWERCASE form:
+//   lexicon['pale'] = "JJ|VBP|NN|VB"      (adjective first)
+//   lexicon['Pale'] = "NNP|RB"            (the capitalised key is the trap)
+//   lexicon['high'] = "JJ|NN|RB|RP"
+// so consulting the lowercase entry recovers the real word class.
+//
+// This runs as the FIRST Calliope step — NOT in the shared `tagfix.ts`, because
+// that seam feeds BOTH engines and would un-freeze Clio.  It corrects the ClsWord
+// POS in place (Calliope's own pre-pass); Clio, invoked via `--clio`, never calls
+// it and so keeps its frozen reading.  (It does not re-run en-parse; the κ/ϕ/ι
+// builder downstream is built to be robust to residual head-attachment errors,
+// and `normalizeDeps` re-derives `canonicalRel` from the corrected POS.)
+//
+// Discipline (anti-gaming): the demotion is gated so it can ONLY fire where the
+// capital is uninformative (sentence/line-initial) and the word is demonstrably a
+// common word, never a known or sequenced proper name.
+
+import { createRequire } from 'module';
+import { ClsSentence, ClsWord } from '../types.js';
+
+const req = createRequire(import.meta.url);
+
+function loadLexicon(): Record<string, string> {
+  try {
+    const m = req('en-lexicon');
+    return (m && (m.lexicon ?? m)) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+const LEXICON = loadLexicon();
+
+const PRONOUN_SUBJECT_CONTRACTIONS_LOCAL = new Set([
+  "i'm", "i'll", "i've", "i'd",
+  "you're", "you'll", "you've", "you'd",
+  "he'll", "he'd", "he's", "she'll", "she'd", "she's", "it'll",
+  "we're", "we'll", "we've", "we'd",
+  "they're", "they'll", "they've", "they'd",
+]);
+
+const PROPER = /^(NNP|NNPS)$/;
+const PUNCT = /^[^A-Za-z0-9]+$/;
+// Content POS, matching parser.ts CONTENT_POS (kept local to avoid a cycle).
+const CONTENT = new Set([
+  'NN', 'NNS', 'NNP', 'NNPS', 'JJ', 'JJR', 'JJS',
+  'VB', 'VBD', 'VBG', 'VBN', 'VBP', 'VBZ', 'RB', 'RBR', 'RBS', 'CD',
+]);
+// Demotion is restricted to the ATTRIBUTIVE/NOMINAL common classes — the exact
+// mis-as-proper class (pale→JJ, slate→NN).  A lowercase-primary that is a finite
+// VERB (rose→VBD) is genuinely ambiguous sentence-initially, so we leave NNP
+// rather than risk a wrong verb tag wrecking the parse.
+const DEMOTE_TARGET = /^(JJ|JJR|JJS|NN|NNS)$/;
+
+function bareLower(w: ClsWord): string {
+  return w.word.toLowerCase().replace(/[^a-z]/g, '');
+}
+function isPunctTag(tag: string): boolean {
+  return PUNCT.test(tag) || tag === '-LRB-' || tag === '-RRB-';
+}
+
+/**
+ * Demote spurious proper-noun tags to their true common reading via en-lexicon.
+ * Mutates `word.lexicalClass` / `word.isContent` in place for the Calliope engine.
+ */
+export function correctPosWithLexicon(sent: ClsSentence): void {
+  const words = sent.words;
+
+  // Index of the first non-punctuation word — the one whose capital is forced by
+  // sentence/line position and therefore carries no proper-noun evidence.
+  let firstContentIdx = -1;
+  for (let i = 0; i < words.length; i++) {
+    if (!isPunctTag(words[i].lexicalClass)) { firstContentIdx = i; break; }
+  }
+
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    if (!PROPER.test(w.lexicalClass)) continue;
+
+    // (a) The lowercase lexicon PRIMARY reading must be an attributive/nominal
+    //     common word.  This — not name-list membership — is the real signal: the
+    //     huge humannames/cities-list flag almost every capitalised common word
+    //     ("Pale", "Slate", "Green" are all in them), so membership cannot gate
+    //     here.  Genuinely proper words are protected instead: their lowercase
+    //     entry is either absent (london, york) or proper-primary (reagan → NNP).
+    const entry = LEXICON[bareLower(w)];
+    if (!entry) continue;
+    const primary = entry.split('|')[0];
+    if (!DEMOTE_TARGET.test(primary)) continue;
+
+    // (b) Caps must be uninformative: the token is the sentence/line-initial word,
+    //     and it is NOT part of a proper-name sequence (a neighbour tagged NNP).
+    if (i !== firstContentIdx) continue;
+    const prev = i > 0 ? words[i - 1] : undefined;
+    const next = i + 1 < words.length ? words[i + 1] : undefined;
+    const adjacentProper =
+      (prev && PROPER.test(prev.lexicalClass)) || (next && PROPER.test(next.lexicalClass));
+    if (adjacentProper) continue;
+
+    w.lexicalClass = primary;
+    w.isContent = CONTENT.has(primary);
+  }
+}
+
+// ─── UDPipe XPOS correction (the role en-pos + tagfix.ts played pre-UD) ──────
+//
+// UDPipe is trained on running prose and systematically MIS-TAGS terse,
+// decontextualised verse fragments — it has no sentence context to lean on.
+// Observed on the test corpus: "hat"→WP, "Woolen"→NNS, "gray"→VBP, "constantly"
+// →NN, "slate"/"clay"→JJ, "bicycle"→NN.  The faithful downstream then scans the
+// garbage.  en-pos avoided this because it is lexicon-backed; we restore that by
+// cross-checking UDPipe's XPOS against en-lexicon's multi-role reading (AGENTS.md:
+// "nounsing-pro / lexicon POS to aid FinNLP… cross-check").  HIGH PRECISION — it
+// only overrides a tag the lexicon positively contradicts; an unknown word keeps
+// UDPipe's tag.
+
+/** Coarse word-class of a Penn tag (N/V/J/R), else the exact tag. */
+function coarseClass(tag: string): string {
+  if (/^(NN|NNS|NNP|NNPS)$/.test(tag)) return 'N';
+  if (/^VB/.test(tag)) return 'V';
+  if (/^JJ/.test(tag)) return 'J';
+  if (/^RB/.test(tag)) return 'R';
+  return tag;
+}
+const NOUN_TAG = /^(NN|NNS|NNP|NNPS)$/;
+
+function retag(w: ClsWord, tag: string): void {
+  w.lexicalClass = tag;
+  w.isContent = CONTENT.has(tag);
+  w.lexicalPlural = tag === 'NNS' || tag === 'NNPS';
+}
+
+/** Is the immediately-preceding non-punctuation word a subject pronoun? */
+function prevIsSubjectPronoun(words: ClsWord[], i: number): boolean {
+  for (let k = i - 1; k >= 0; k--) {
+    if (isPunctTag(words[k].lexicalClass)) continue;
+    const rel = (words[k].dependency?.dependentType ?? '').toLowerCase();
+    return words[k].lexicalClass === 'PRP' && /nsubj/.test(rel);
+  }
+  return false;
+}
+
+/** Next non-punctuation word, or undefined. */
+function nextContentful(words: ClsWord[], i: number): ClsWord | undefined {
+  for (let k = i + 1; k < words.length; k++) {
+    if (!isPunctTag(words[k].lexicalClass)) return words[k];
+  }
+  return undefined;
+}
+
+export function correctUDPipePos(sent: ClsSentence): void {
+  const words = sent.words;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    if (isPunctTag(w.lexicalClass)) continue;
+
+    // (0) CONTRACTED SUBJECT PRONOUNS: UDPipe/FinNLP often mis-tags
+    //     "I'll", "I've", "I'd", "I'm" as JJ, NNP, or other content classes,
+    //     giving them a spurious content beat. Correct them to PRP (personal
+    //     pronoun) so they floor to 'w' or 'n' like other pronouns.
+    const lowerWord = w.word.toLowerCase().replace(/[’]/g, "'");
+    if (PRONOUN_SUBJECT_CONTRACTIONS_LOCAL.has(lowerWord)) {
+      retag(w, 'PRP');
+      continue;
+    }
+
+    // (0) POSSESSIVE clitic mis-tagged as a verb: UDPipe tags the genitive "'s"
+    //     in "laugher's licence" as VBZ (confusing it with the copula "he's" = he
+    //     is), giving the clitic a spurious content beat.  The genitive 's carries
+    //     a `case` relation onto its possessor noun; the copula does not — so that
+    //     relation distinguishes them.  Retag POS (0 syllables downstream).
+    // (0) POSSESSIVE clitic mis-tagged as a verb: UDPipe sometimes tags the
+    //     genitive "'s" (in "laugher's licence") as VBZ — confusing it with the
+    //     copula "he's" = he is — giving the clitic a spurious content beat.  The
+    //     genitive 's carries a `case` relation onto its possessor noun; the copula
+    //     does not — so that relation distinguishes them.  Retag POS.
+    if ((w.word === "'s" || w.word === "’s") && /^VB/.test(w.lexicalClass)
+        && (w.dependency?.dependentType ?? '').toLowerCase() === 'case') {
+      retag(w, 'POS');
+      continue;
+    }
+    // The possessive ending itself is never corrected by the lexicon pass below
+    // (en-lexicon has a spurious verb entry for the bare letter "s").
+    if (w.lexicalClass === 'POS') continue;
+
+    const lemma = bareLower(w);
+    if (lemma.length <= 1) continue;                        // "s"/"a"/"o" → too ambiguous
+    const entry = LEXICON[lemma];
+    if (!entry) continue;                                   // unknown → trust UDPipe
+    const classes = entry.split('|');
+    const primary = classes[0];
+    const lexCoarse = new Set(classes.map(coarseClass));
+    const udCoarse = coarseClass(w.lexicalClass);
+    const CONTENT_COARSE = new Set(['N', 'V', 'J', 'R']);
+
+    // (1) PLAUSIBILITY: UDPipe's coarse class is absent from the lexicon entirely
+    //     (hat→WP, Woolen→NNS, constantly→NN, clay→JJ) → fall back to the lexicon's
+    //     primary reading.  Only fires on a positive contradiction AND only when the
+    //     correction is TOWARD a content class (never invents a function tag).
+    if (!lexCoarse.has(udCoarse) && CONTENT_COARSE.has(coarseClass(primary))
+        && coarseClass(primary) !== udCoarse) {
+      retag(w, primary);
+      continue;
+    }
+
+    // (2) ATTRIBUTIVE NOUN mis-tagged JJ: a lexicon-primary noun UDPipe tagged JJ,
+    //     sitting immediately before a noun, is the modifier of an N+N compound
+    //     ("SLATE roof", "CLAY jar"), not an adjective.  Retag NN so the compound
+    //     fore-stresses (deps.ts NOMD).
+    if (/^JJ/.test(w.lexicalClass) && coarseClass(primary) === 'N') {
+      const nxt = nextContentful(words, i);
+      if (nxt && NOUN_TAG.test(nxt.lexicalClass) && nxt.absoluteIndex === w.absoluteIndex + 1) {
+        retag(w, 'NN');
+        continue;
+      }
+    }
+
+    // (3) NOUN that should be a finite VERB: a lexicon-verb-capable common noun
+    //     UDPipe tagged NN, immediately preceded by a SUBJECT PRONOUN ("they
+    //     BICYCLE through", "we PAPER walls"), is the clause's predicate → VBP.
+    if (NOUN_TAG.test(w.lexicalClass) && lexCoarse.has('V') && prevIsSubjectPronoun(words, i)) {
+      retag(w, 'VBP');
+      continue;
+    }
+
+    // (4) TEMPORAL ADVERB mis-tagged IN: "before"/"after"/"since"/"once" tagged IN
+    //     but with no nominal complement before the next clause boundary is an
+    //     adverb (RB), not a preposition.  Penn treebank: IN takes an NP
+    //     complement ("before the storm"); RB does not ("never before", "long
+    //     after").  A following verb/pronoun signals a subordinate clause ("before
+    //     I go") → leave as IN (subordinating conjunction sense).
+    const TEMPORAL_ADVS = new Set(['before', 'after', 'since', 'once']);
+    if (w.lexicalClass === 'IN' && TEMPORAL_ADVS.has(lemma)) {
+      let hasNoun = false, hasClauseStart = false;
+      for (let k = i + 1; k < words.length; k++) {
+        if (isPunctTag(words[k].lexicalClass)) break;
+        if (NOUN_TAG.test(words[k].lexicalClass)) { hasNoun = true; break; }
+        if (/^(VB|VBP|VBD|VBG|VBN|VBZ|PRP)$/.test(words[k].lexicalClass)) hasClauseStart = true;
+      }
+      if (!hasNoun && !hasClauseStart) {
+        retag(w, 'RB');
+        continue;
+      }
+    }
+  }
+}

package/src/calliope/prosodic.ts

@@ -0,0 +1,262 @@
+// calliope/prosodic.ts — the Match-Theory prosodic hierarchy for Calliope.
+//
+// Builds the κ (clitic group) / ϕ (phonological phrase) / ι (intonational unit)
+// structure from the canonical dependency relations and the REAL utterance
+// boundaries — replacing the legacy builder (phonological.ts), which split an IU
+// at every comma and grouped phrases off the constituent tree.  The corrections,
+// per McAleese A1/A2 and the maintainer's critique:
+//
+//   ι  only at genuine intonational breaks: terminal punctuation (. ? !), colon,
+//      semicolon, and parentheticals.  A plain COMMA is NOT an ι — it is a minor
+//      ϕ break.  (This is the "utterance boundaries, not line breaks / not every
+//      comma" fix.)
+//   ϕ  at: a comma; the head of an oblique PP (a preposition opens a new phrase —
+//      "…compare thee | to a summer's day"); each coordinate conjunct; a clause
+//      complement (CCOMP/XCOMP/ADVCL); and the junction between a full nominal
+//      SUBJECT and its predicate verb.
+//   κ  a content head plus its function words by DIRECTION: determiners, case
+//      markers/prepositions, auxiliaries, coordinators, complementisers, numerals,
+//      possessives and (sub/obj) pronouns procliticise rightward onto the following
+//      head; the possessive 's and verb particles encliticise leftward.  A trailing
+//      proclitic with no head to its right attaches to the preceding group (so
+//      "…compare thee" keeps the object pronoun in the verb's group).
+//
+// Output is the shared IntonationalUnit[] shape, so display/scansion are unchanged.
+// It reads only POS + canonicalRel + surface order; it never mutates the parse.
+
+import {
+  ClsSentence, ClsWord, CliticGroup, PhonologicalPhrase, IntonationalUnit,
+} from '../types.js';
+import { computePhiDomains } from './bracketing.js';
+
+// ─── punctuation → break kind ──────────────────────────────────────
+const IU_PUNCT_TAGS = new Set(['.', '!', '?', ':', ';', '-LRB-', '-RRB-', '(', ')']);
+const IU_PUNCT_WORDS = new Set(['.', '!', '?', '…', ':', ';', '(', ')']);
+
+type BreakKind = 'iu' | 'phi' | null;
+function breakKind(w: ClsWord): BreakKind {
+  if (IU_PUNCT_TAGS.has(w.lexicalClass) || IU_PUNCT_WORDS.has(w.word)) return 'iu';
+  if (w.lexicalClass === ',' || w.word === ',') return 'phi';
+  return null; // other punctuation (quotes, etc.) — transparent to phrasing
+}
+function isAnyPunct(w: ClsWord): boolean {
+  return /^[^A-Za-z0-9]+$/.test(w.lexicalClass) ||
+    w.lexicalClass === '-LRB-' || w.lexicalClass === '-RRB-';
+}
+
+// ─── κ: directional cliticisation ──────────────────────────────────
+const PROCLITIC_REL = new Set([
+  'DET', 'CASE', 'AUX', 'AUXPASS', 'CC', 'COMPMARK', 'ADVMARK', 'NUMMOD', 'EXPL',
+]);
+const PROCLITIC_POS = /^(DT|PDT|IN|TO|CC|MD|WDT|WP|WP\$|EX|PRP\$|PRP)$/;
+
+const OBJECT_REL = new Set(['DOBJ', 'IOBJ', 'OBL', 'OBJ']);
+
+/** A clitic that leans LEFTWARD onto the preceding head (possessive 's, particle,
+ *  OBJECT pronoun).  An object pronoun encliticises to its verb ("compare thee",
+ *  "give me") — so it must NOT be pulled rightward into the next phrase, which is
+ *  what buried the preposition in "…compare thee | to a summer's day". */
+function isEnclitic(w: ClsWord): boolean {
+  if (w.lexicalClass === 'POS' || w.lexicalClass === 'RP' || w.canonicalRel === 'VPRT') return true;
+  if (w.lexicalClass === 'PRP' && OBJECT_REL.has(w.canonicalRel ?? '')) return true;
+  return false;
+}
+/** A function word that leans RIGHTWARD onto the following content head. */
+function isProclitic(w: ClsWord): boolean {
+  if (w.isContent) return false;             // a promoted particle/demonstrative is a head
+  if (isEnclitic(w)) return false;
+  if (PROCLITIC_REL.has(w.canonicalRel ?? '')) return true;
+  return PROCLITIC_POS.test(w.lexicalClass);
+}
+
+/** Build clitic groups over one IU segment's content/function words (no punct). */
+function buildCliticGroups(words: ClsWord[]): CliticGroup[] {
+  const groups: CliticGroup[] = [];
+  let pending: ClsWord[] = [];               // proclitics awaiting their head
+  for (const w of words) {
+    if (isEnclitic(w) && groups.length > 0 && pending.length === 0) {
+      groups[groups.length - 1].tokens.push(w);
+      continue;
+    }
+    if (isProclitic(w)) { pending.push(w); continue; }
+    // content head (or any non-clitic): open a CP with its pending proclitics.
+    groups.push({ tokens: [...pending, w] });
+    pending = [];
+  }
+  if (pending.length) {
+    if (groups.length) groups[groups.length - 1].tokens.push(...pending);
+    else groups.push({ tokens: pending });
+  }
+  return groups;
+}
+
+// ─── ϕ: phrase grouping (by dependency ϕ-domain) ───────────────────
+// A ϕ boundary opens between two clitic groups when they fall in DIFFERENT
+// ϕ-domains of the dependency tree (computePhiDomains, bracketing.ts) — the
+// SAME constituent structure the cyclic stress rules use — replacing the old
+// POS-keyed opensPhrase heuristic.  So a stranded particle no longer opens a
+// spurious oblique ϕ ("thought of" stays together), a branching object NP gets
+// its own ϕ (reading | the latest biography), and a clause does not flatten
+// when its head is mis-tagged (the relations, not the POS, decide).
+
+function rightmostContent(cg: CliticGroup): ClsWord | undefined {
+  for (let i = cg.tokens.length - 1; i >= 0; i--) if (cg.tokens[i].isContent) return cg.tokens[i];
+  return cg.tokens[cg.tokens.length - 1];
+}
+
+/** The ϕ-domain id a clitic group sits in: the domain of its head (rightmost
+ *  content word, else last token); a function-only group falls back to any of
+ *  its tokens' domains (its proclitics share the domain of the head they lean
+ *  onto).  A new ϕ opens whenever this id changes between adjacent groups. */
+function domainOf(cg: CliticGroup, dom: Map<ClsWord, number>): number {
+  const head = rightmostContent(cg) ?? cg.tokens[cg.tokens.length - 1];
+  const d = dom.get(head);
+  if (d !== undefined) return d;
+  for (const t of cg.tokens) { const dd = dom.get(t); if (dd !== undefined) return dd; }
+  return -1;
+}
+
+/** Two PARSE-ROBUST ϕ-boundary markers from McAleese's Table-1 that the
+ *  dependency-domain core cannot see when en-parse mis-attaches:
+ *
+ *   • a COORDINATOR (CC "and / or / but") — each coordinate conjunct is its own
+ *     ϕ; en-parse often flattens "old and gray and full" into a list of AMODs,
+ *     so the conj relation is gone, but the CC token survives reliably.
+ *   • a RELATIVE PRONOUN (WDT/WP "that / which / who") — it opens the relative
+ *     clause's ϕ; en-parse routinely fails to build the ACL ("…the cat that
+ *     caught the rat" flattened into one clause), but the relativiser is tagged.
+ *
+ *  These are the two Table-1 triggers that survive attachment errors, so they
+ *  supplement the dependency domains rather than re-introducing POS guesswork. */
+function startsCoordOrRelative(cg: CliticGroup): boolean {
+  const t = cg.tokens[0];
+  if (!t) return false;
+  if (t.lexicalClass === 'CC' || t.canonicalRel === 'CC') return true;
+  return /^(WDT|WP|WP\$)$/.test(t.lexicalClass);
+}
+
+// A φ needs a stress-bearing ANCHOR to stand on its own.  A content word is the
+// usual one, but the 'n'-tier function words — demonstratives, quantifiers, and
+// wh-words (relstress.functionLevel → 'n') — also carry a real beat, so a phrase
+// built around one ("for THAT", "to EACH", "by WHICH") is a genuine φ with a
+// nuclear and must NOT be dissolved into a neighbour the way a pure article /
+// preposition / pronoun run ("around it") is.  (Lemma/POS list mirrors relstress'
+// 'n' category; kept local so the hierarchy layer does not depend on the stress one.)
+const ANCHOR_LEMMAS = new Set([
+  'this', 'that', 'these', 'those',
+  'all', 'both', 'each', 'every', 'some', 'any', 'many', 'much', 'few', 'most',
+  'half', 'several', 'either', 'neither', 'enough', 'none',
+]);
+const ANCHOR_POS = /^(PDT|WDT|WP|WP\$|WRB)$/;
+function canAnchorBeat(pp: PhonologicalPhrase): boolean {
+  return pp.cliticGroups.some(cg => cg.tokens.some(t =>
+    t.isContent ||
+    /^VB/.test(t.lexicalClass) ||        // a verb group ("has been") is a real ϕ even
+                                          // when its tokens are non-content auxiliaries —
+                                          // it must not fold back into the subject NP
+    ANCHOR_LEMMAS.has(t.word.toLowerCase().replace(/['’]/g, '')) ||
+    ANCHOR_POS.test(t.lexicalClass)));
+}
+
+function groupIntoPhrases(
+  cgs: CliticGroup[], commaBeforeCG: Set<CliticGroup>, dom: Map<ClsWord, number>
+): PhonologicalPhrase[] {
+  const phrases: { cgs: CliticGroup[]; commaPreceded: boolean }[] = [];
+  let current: CliticGroup[] = [];
+  let prev: CliticGroup | null = null;
+  let currentCommaPreceded = false;
+  for (const cg of cgs) {
+    const brk = current.length > 0 && prev !== null &&
+      (commaBeforeCG.has(cg) || startsCoordOrRelative(cg) ||
+       domainOf(cg, dom) !== domainOf(prev, dom));
+    if (brk) {
+      phrases.push({ cgs: current, commaPreceded: currentCommaPreceded });
+      current = [];
+      currentCommaPreceded = commaBeforeCG.has(cg);
+    }
+    current.push(cg);
+    prev = cg;
+  }
+  if (current.length) phrases.push({ cgs: current, commaPreceded: currentCommaPreceded });
+
+  // A ϕ must have a beat-anchor: a phrase of only un-anchored function words (a
+  // stranded preposition + pronoun like "around it", an orphan determiner) has no
+  // nuclear to carry a beat, so it MERGES into its neighbour — into the previous
+  // phrase when there is one (it leans back onto the head it modifies), else the
+  // next.  A phrase anchored by a demonstrative/quantifier/wh ("for THAT") is NOT
+  // merged — it is a genuine φ.
+  //
+  // BUT: a phrase preceded by a COMMA is NEVER merged, even if it lacks a
+  // beat-anchor.  A comma is an OVERT prosodic boundary the poet placed; merging
+  // across it destroys the boundary and flattens the post-comma material into the
+  // pre-comma phrase ("among them" after "And of the best," → xww instead of xnw).
+  // A function-word-only post-comma phrase keeps its separate ϕ so the
+  // relativiser can apply the phrase-initial beat and the givenness escape.
+  const merged: PhonologicalPhrase[] = [];
+  for (const p of phrases) {
+    const pp: PhonologicalPhrase = { cliticGroups: p.cgs };
+    if (!canAnchorBeat(pp) && merged.length > 0 && !p.commaPreceded) {
+      merged[merged.length - 1].cliticGroups.push(...p.cgs);
+    } else {
+      merged.push(pp);
+    }
+  }
+  // A leading un-anchored phrase folds forward into the next — but NOT if it was
+  // comma-preceded (a comma before the first phrase would be line-initial, which
+  // doesn't happen; this guard is for safety).
+  if (merged.length >= 2 && !canAnchorBeat(merged[0]) && !phrases[0].commaPreceded) {
+    merged[1].cliticGroups.unshift(...merged[0].cliticGroups);
+    merged.shift();
+  }
+  return merged;
+}
+
+// ─── top level ─────────────────────────────────────────────────────
+export function buildProsodicHierarchy(sent: ClsSentence): IntonationalUnit[] {
+  // ϕ-domains over the dependency tree (the same constituent structure the
+  // cyclic stress rules use) — the grouping signal for phonological phrases.
+  const dom = computePhiDomains(sent);
+
+  const ius: IntonationalUnit[] = [];
+  let segWords: ClsWord[] = [];
+  let commaAfterPos = new Set<number>();      // positions in segWords with a comma after
+
+  const flush = () => {
+    if (segWords.length === 0) { commaAfterPos = new Set(); return; }
+    // A φ-break (comma) is a HARD boundary for clitic-group formation: a proclitic
+    // must not lean across a comma onto a head in the next phrase.  (Letting it do
+    // so silently glued "for that ," onto the following "a specialized branch" — both
+    // "for" and "that" procliticise rightward onto "specialized" — so the comma fell
+    // INSIDE one clitic group and the φ-break was lost.)  So we split the IU segment
+    // into RUNS at the comma positions, build clitic groups WITHIN each run, and mark
+    // the first CG of every run after the first as φ-preceded.
+    const runs: ClsWord[][] = [];
+    let run: ClsWord[] = [];
+    segWords.forEach((w, i) => {
+      run.push(w);
+      if (commaAfterPos.has(i)) { runs.push(run); run = []; }
+    });
+    if (run.length) runs.push(run);
+
+    const cgs: CliticGroup[] = [];
+    const commaBeforeCG = new Set<CliticGroup>();
+    runs.forEach((r, ri) => {
+      const rcgs = buildCliticGroups(r);
+      if (ri > 0 && rcgs.length > 0) commaBeforeCG.add(rcgs[0]);
+      cgs.push(...rcgs);
+    });
+    ius.push({ phonologicalPhrases: groupIntoPhrases(cgs, commaBeforeCG, dom) });
+    segWords = [];
+    commaAfterPos = new Set();
+  };
+
+  for (const w of sent.words) {
+    const kind = breakKind(w);
+    if (kind === 'iu') { flush(); continue; }
+    if (kind === 'phi') { if (segWords.length) commaAfterPos.add(segWords.length - 1); continue; }
+    if (isAnyPunct(w)) continue;              // transparent punctuation
+    segWords.push(w);
+  }
+  flush();
+  return ius;
+}