calliope-ts 0.0.2 → 0.0.3

package/src/scansion.ts

@@ -612,10 +612,20 @@ function buildScansionString(syls: FlatSyl[], feet: number[], ius?: Intonational
 
 // ─── 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: number): string {
-  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 ────────────────────────────────────────
@@ -631,6 +641,7 @@ const METER_PRIOR: Partial<Record<MetreName, number>> = { iambic: 0.02 };
 // enough that it never overturns a clearly-duple line.
 const TERNARY_BIAS = 0.02;
 const TERNARY_METERS = new Set<MetreName>(['anapestic', 'dactylic', 'amphibrachic', 'bacchic']);
+const DUPLE_METERS = new Set<MetreName>(['iambic', 'trochaic']);
 
 // Weights against the (0..1) normalised fit fraction.
 const REDGE_WEIGHT = 0.28;   // right-edge (key-stress) agreement — disambiguates polarity
@@ -658,6 +669,71 @@ function onsetBonus(flat: FlatSyl[], meter: MetreName): number {
   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: MeterScore[]): boolean {
+  const top = ranking.slice(0, 3).map(r => r.meter as MetreName);
+  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: PhonologicalScansionDetail): string | undefined {
+  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: PhonologicalScansionDetail[]): void {
+  for (const d of details) d.metricalityNote = metricalityVerdict(d);
+}
+
 export function scoreMeters(
   keyStresses: KeyStress[],
   words: ClsWord[],
@@ -938,7 +1014,9 @@ export function applyRhythmLayer(details: PhonologicalScansionDetail[]): void {
           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).
           const mode = [...new Set(counts)].map(v => [v, counts.filter(c => c === v).length] as const)
@@ -952,9 +1030,14 @@ export function applyRhythmLayer(details: PhonologicalScansionDetail[]): void {
             else if (family === 'accentual') note = `${mode[0]}-beat accentual`;
             // 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) d.rhythmNote = note;
       }
@@ -996,15 +1079,28 @@ export function applyStanzaConsensus(
     if (d.meterName === 'free verse') 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: string[] = [];
   for (const [m, c] of counts) {
-    if (c > max) { max = c; dominant = m; tied = false; }
-    else if (c === max) tied = true;
+    if (c > max) { max = c; atMax.length = 0; atMax.push(m); }
+    else if (c === max) atMax.push(m);
   }
-  if (max < 2 || tied || !dominant) return;
+  if (max < 2) return;
+  if (atMax.length === 1) {
+    dominant = atMax[0];
+  } else {
+    const mass = (name: string) => 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
@@ -1019,7 +1115,25 @@ export function applyStanzaConsensus(
     for (const d of details) {
       if (!TERNARY_METERS.has(d.meterName as MetreName)) 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 as MetreName)) {
+        // 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: number) => anacs.includes(v);
@@ -1041,9 +1155,16 @@ export function applyStanzaConsensus(
     // 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 as MetreName)
-      && TERNARY_METERS.has(dominant as MetreName);
+    // 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 as MetreName)
+        && TERNARY_METERS.has(dominant as MetreName))
+      || (DUPLE_METERS.has(d.meterName as MetreName)
+        && DUPLE_METERS.has(dominant as MetreName));
     const threshold = siblings ? 0.95 : tie;
     if (own > 0 && dom >= own * threshold) {
       const lengthWord = d.meter.split(' ')[1] ?? '';

package/src/semantics.ts

@@ -0,0 +1,134 @@
+// 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 { ClsWord } from './types.js';
+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: ClsWord, words: ClsWord[]): boolean {
+  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: ClsWord, words: ClsWord[]): boolean {
+  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: ClsWord, words: ClsWord[]): boolean {
+  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: ClsWord, words: ClsWord[]): boolean {
+  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: ClsWord, words: ClsWord[]): boolean {
+  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: ClsWord[]): boolean {
+  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: ClsWord, words: ClsWord[]): boolean {
+  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);
+}