calendar: occurrence engine v2 — real rank thresholds, transfers, collisions

Corrects and completes the occurrence rules, based on a design discussion
plus one concrete data point: St. Anthony Abbot (plain Duplex) was found
outright winning against an ordinary Sunday in the real Monastic 1617
engine, which the old duplex-1-classis-only threshold got wrong.

- FeastClass gains `vigil`, inserted between `simplex` and `semiduplex` —
  one ordering that correctly serves both "does this win against a Sunday"
  (vigil behaves like simplex there) and "which of two saints wins a
  landing-day collision" (vigil beats simplex, loses to semiduplex).
- LiturgicalDay.occurring (a flat OccurringFeast[] that could only ever
  express a losing *sanctoral* candidate) is replaced by `winner:
  DayWinner` + `commemorations: Commemoration[]` — a discriminated list
  that can hold the temporal day itself, one or more sanctoral entries, or
  (not built yet, but the shape already accommodates it) a future octave
  kind.
- commemorations.ts: ordinary Sundays let Duplex+ win outright (Sunday
  commemorated in return), Semiduplex/Vigil transfer elsewhere (too
  substantial a feast to cheapen with a bare commemoration), Simplex stays
  and is commemorated. Privileged Sundays never displace; Duplex-majus+
  commemorated, everything else transfers.
- collision.ts (new): resolves two sanctoral candidates wanting the same
  day (a transfer landing on an already-occupied day, or two native
  saints sharing a date) — duplex > semiduplex > vigil > simplex, loser
  always commemorated, ties favor the native occupant.
- temporal-id.ts (new): maps any date to one of the 52 real Sunday-collect
  ids from the previous commit, so a temporal winner/commemoration can
  actually be looked up, not just labeled "temporal" in the abstract.
- index.ts's resolveDay orchestrates all of it, including the actual
  Monday/Saturday transfer mechanism. Landing on a privileged feria (the
  concrete case: Holy Week, right after Palm Sunday) is explicitly
  deferred rather than guessed at — it needs its own Easter-keyed lookup
  table, the same way the reference engine handles it.

Added the Vigil of St. Lawrence (Aug 9) as real content specifically to
exercise the backward-transfer rule end-to-end: Aug 9, 2026 is a Sunday,
so the vigil transfers cleanly back to Saturday, verified by a new
integration test alongside the unit-level rule and collision tests.

tests/calendar/collision.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { resolveCollision } from '../../src/calendar/collision';
+import type { SanctoralIdentity } from '../../src/calendar/types';
+
+function saint(id: string, rank: SanctoralIdentity['rank']): SanctoralIdentity {
+  return { id, name: id, rank };
+}
+
+describe('resolveCollision', () => {
+  it('higher rank wins regardless of which side is incoming vs native', () => {
+    const incoming = saint('incoming', 'semiduplex');
+    const native = saint('native', 'simplex');
+    const result = resolveCollision(incoming, native);
+    expect(result.winner).toEqual({ kind: 'sanctoral', id: 'incoming', name: 'incoming', rank: 'semiduplex' });
+    expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'native', name: 'native', rank: 'simplex' }]);
+  });
+
+  it('a transferred Vigil beats a native Simplex (vigil ranks above simplex for collisions)', () => {
+    const result = resolveCollision(saint('vigil-feast', 'vigil'), saint('native', 'simplex'));
+    expect(result.winner.kind).toBe('sanctoral');
+    expect(result.winner.kind === 'sanctoral' ? result.winner.id : undefined).toBe('vigil-feast');
+  });
+
+  it('a native Semiduplex beats a transferred Vigil', () => {
+    const result = resolveCollision(saint('vigil-feast', 'vigil'), saint('native', 'semiduplex'));
+    expect(result.winner.kind === 'sanctoral' ? result.winner.id : undefined).toBe('native');
+    expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'vigil-feast', name: 'vigil-feast', rank: 'vigil' }]);
+  });
+
+  it('ties favor the native occupant, the incoming feast is commemorated', () => {
+    const result = resolveCollision(saint('incoming', 'duplex'), saint('native', 'duplex'));
+    expect(result.winner.kind === 'sanctoral' ? result.winner.id : undefined).toBe('native');
+    expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'incoming', name: 'incoming', rank: 'duplex' }]);
+  });
+
+  it('the loser is always commemorated, with no rank threshold', () => {
+    const result = resolveCollision(saint('incoming', 'duplex-1-classis'), saint('native', 'simplex'));
+    expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'native', name: 'native', rank: 'simplex' }]);
+  });
+});

tests/calendar/commemorations.test.ts

@@ -1,9 +1,16 @@
 import { describe, expect, it } from 'vitest';
 import { decideOccurrence, compareFeastClass, isAtLeast } from '../../src/calendar/commemorations';
+import type { SanctoralIdentity } from '../../src/calendar/types';
+
+function saint(rank: SanctoralIdentity['rank']): SanctoralIdentity {
+  return { id: 'x', name: 'St. Ereden', rank };
+}
 
 describe('compareFeastClass / isAtLeast', () => {
-  it('orders the six ranks low to high', () => {
-    expect(compareFeastClass('simplex', 'duplex-1-classis')).toBeLessThan(0);
+  it('orders the seven ranks low to high, with vigil between simplex and semiduplex', () => {
+    expect(compareFeastClass('simplex', 'vigil')).toBeLessThan(0);
+    expect(compareFeastClass('vigil', 'semiduplex')).toBeLessThan(0);
+    expect(compareFeastClass('semiduplex', 'duplex')).toBeLessThan(0);
     expect(compareFeastClass('duplex-1-classis', 'simplex')).toBeGreaterThan(0);
     expect(compareFeastClass('duplex', 'duplex')).toBe(0);
   });
@@ -14,56 +21,85 @@ describe('compareFeastClass / isAtLeast', () => {
   });
 });
 
-describe('decideOccurrence', () => {
+describe('decideOccurrence — no candidate', () => {
   it('temporal wins trivially when nothing is assigned to the date', () => {
-    expect(decideOccurrence('ordinary-feria', null)).toEqual({ winner: 'temporal', commemorated: false });
-    expect(decideOccurrence('privileged-sunday', null)).toEqual({ winner: 'temporal', commemorated: false });
-  });
-
-  it('an ordinary feria always yields to any real feast, uncommemorated', () => {
-    expect(decideOccurrence('ordinary-feria', 'simplex')).toEqual({ winner: 'sanctoral', commemorated: false });
-    expect(decideOccurrence('ordinary-feria', 'duplex-1-classis')).toEqual({ winner: 'sanctoral', commemorated: false });
-  });
-
-  it('a privileged feria yields to nothing short of the top class', () => {
-    expect(decideOccurrence('privileged-feria', 'duplex-2-classis')).toEqual({
-      winner: 'temporal',
-      commemorated: false,
-    });
-    expect(decideOccurrence('privileged-feria', 'duplex-1-classis')).toEqual({
-      winner: 'temporal',
-      commemorated: true,
-    });
-  });
-
-  it('an ordinary Sunday yields outright only to the top class, and is commemorated by the two ranks below it', () => {
-    expect(decideOccurrence('ordinary-sunday', 'duplex-1-classis')).toEqual({
-      winner: 'sanctoral',
-      commemorated: false,
-    });
-    expect(decideOccurrence('ordinary-sunday', 'duplex-2-classis')).toEqual({
-      winner: 'temporal',
-      commemorated: true,
-    });
-    expect(decideOccurrence('ordinary-sunday', 'duplex-majus')).toEqual({
-      winner: 'temporal',
-      commemorated: true,
-    });
-    expect(decideOccurrence('ordinary-sunday', 'duplex')).toEqual({ winner: 'temporal', commemorated: false });
-  });
-
-  it('a privileged Sunday is never displaced, and only the top two ranks are even commemorated', () => {
-    expect(decideOccurrence('privileged-sunday', 'duplex-1-classis')).toEqual({
-      winner: 'temporal',
-      commemorated: true,
-    });
-    expect(decideOccurrence('privileged-sunday', 'duplex-2-classis')).toEqual({
-      winner: 'temporal',
-      commemorated: true,
-    });
-    expect(decideOccurrence('privileged-sunday', 'duplex-majus')).toEqual({
-      winner: 'temporal',
-      commemorated: false,
+    expect(decideOccurrence('ordinary-feria', 'some-feria-id', null)).toEqual({
+      winner: { kind: 'temporal', id: 'some-feria-id' },
+      commemorations: [],
     });
   });
 });
+
+describe('decideOccurrence — ordinary-feria', () => {
+  it('always yields to any real feast, uncommemorated, whatever its rank', () => {
+    for (const rank of ['simplex', 'vigil', 'semiduplex', 'duplex', 'duplex-1-classis'] as const) {
+      const result = decideOccurrence('ordinary-feria', 'id', saint(rank));
+      expect(result.winner).toEqual({ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank });
+      expect(result.commemorations).toEqual([]);
+      expect(result.transfer).toBeUndefined();
+    }
+  });
+});
+
+describe('decideOccurrence — privileged-feria', () => {
+  it('yields to nothing short of the top class', () => {
+    const majus = decideOccurrence('privileged-feria', 'id', saint('duplex-2-classis'));
+    expect(majus.winner).toEqual({ kind: 'temporal', id: 'id' });
+    expect(majus.commemorations).toEqual([]);
+
+    const top = decideOccurrence('privileged-feria', 'id', saint('duplex-1-classis'));
+    expect(top.commemorations).toEqual([{ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank: 'duplex-1-classis' }]);
+  });
+});
+
+describe('decideOccurrence — ordinary-sunday', () => {
+  it('duplex or higher wins outright, and the Sunday itself is commemorated', () => {
+    const result = decideOccurrence('ordinary-sunday', 'post-epiphany-2', saint('duplex'));
+    expect(result.winner).toEqual({ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank: 'duplex' });
+    expect(result.commemorations).toEqual([{ kind: 'temporal', id: 'post-epiphany-2' }]);
+    expect(result.transfer).toBeUndefined();
+  });
+
+  it('simplex stays and is commemorated, not transferred', () => {
+    const result = decideOccurrence('ordinary-sunday', 'post-epiphany-2', saint('simplex'));
+    expect(result.winner).toEqual({ kind: 'temporal', id: 'post-epiphany-2' });
+    expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank: 'simplex' }]);
+    expect(result.transfer).toBeUndefined();
+  });
+
+  it('semiduplex gets nothing here — transfers forward', () => {
+    const result = decideOccurrence('ordinary-sunday', 'post-epiphany-2', saint('semiduplex'));
+    expect(result.winner).toEqual({ kind: 'temporal', id: 'post-epiphany-2' });
+    expect(result.commemorations).toEqual([]);
+    expect(result.transfer).toEqual({ candidate: saint('semiduplex'), direction: 'forward' });
+  });
+
+  it('vigil gets nothing here — transfers backward', () => {
+    const result = decideOccurrence('ordinary-sunday', 'post-epiphany-2', saint('vigil'));
+    expect(result.transfer).toEqual({ candidate: saint('vigil'), direction: 'backward' });
+  });
+});
+
+describe('decideOccurrence — privileged-sunday', () => {
+  it('is never displaced; duplex-majus and up are commemorated', () => {
+    for (const rank of ['duplex-majus', 'duplex-2-classis', 'duplex-1-classis'] as const) {
+      const result = decideOccurrence('privileged-sunday', 'advent-1', saint(rank));
+      expect(result.winner).toEqual({ kind: 'temporal', id: 'advent-1' });
+      expect(result.commemorations).toEqual([{ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank }]);
+      expect(result.transfer).toBeUndefined();
+    }
+  });
+
+  it('duplex, semiduplex, and simplex all transfer forward — no bare commemoration here', () => {
+    for (const rank of ['duplex', 'semiduplex', 'simplex'] as const) {
+      const result = decideOccurrence('privileged-sunday', 'advent-1', saint(rank));
+      expect(result.commemorations).toEqual([]);
+      expect(result.transfer).toEqual({ candidate: saint(rank), direction: 'forward' });
+    }
+  });
+
+  it('vigil transfers backward, same as on an ordinary Sunday', () => {
+    const result = decideOccurrence('privileged-sunday', 'advent-1', saint('vigil'));
+    expect(result.transfer).toEqual({ candidate: saint('vigil'), direction: 'backward' });
+  });
+});

tests/calendar/day-label.test.ts

@@ -38,13 +38,14 @@ describe('getDayLabel — feast name combination', () => {
     weekday: 'monday',
     season: 'trinitytide',
     temporalCategory: 'ordinary-feria',
-    occurring: [],
+    winner: { kind: 'temporal', id: 'post-pentecost-02' },
+    commemorations: [],
   };
 
   it('shows just the feast name when it wins outright', () => {
     const day: LiturgicalDay = {
       ...base,
-      occurring: [{ id: 'x', name: 'St. Ereden', rank: 'duplex', commemorated: false }],
+      winner: { kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank: 'duplex' },
     };
     expect(getDayLabel(day)).toBe('St. Ereden');
   });
@@ -52,12 +53,12 @@ describe('getDayLabel — feast name combination', () => {
   it('shows both, feast first, when the feast is merely commemorated', () => {
     const day: LiturgicalDay = {
       ...base,
-      occurring: [{ id: 'x', name: 'St. Ereden', rank: 'duplex-2-classis', commemorated: true }],
+      commemorations: [{ kind: 'sanctoral', id: 'x', name: 'St. Ereden', rank: 'duplex-2-classis' }],
     };
     expect(getDayLabel(day)).toBe('St. Ereden — Monday in the 2nd week after Trinity');
   });
 
-  it('shows just the temporal label when nothing is occurring at all', () => {
+  it('shows just the temporal label when nothing is commemorated at all', () => {
     expect(getDayLabel(base)).toBe('Monday in the 2nd week after Trinity');
   });
 });

tests/calendar/transfer.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { resolveDay } from '../../src/calendar';
+
+describe('transfer mechanism (resolveDay integration)', () => {
+  // The Vigil of St. Lawrence (Aug 9) is a real content entry specifically
+  // added to exercise this — Aug 9, 2026 is a Sunday, so the vigil (rank
+  // 'vigil') can't win or be commemorated there (see
+  // commemorations.ts's ordinary-sunday rule) and must transfer backward.
+  it('a vigil impeded by an ordinary Sunday transfers backward to Saturday, leaving the Sunday untouched', () => {
+    const saturday = resolveDay('2026-08-08');
+    const sunday = resolveDay('2026-08-09');
+    const monday = resolveDay('2026-08-10');
+
+    expect(saturday.winner).toEqual({
+      kind: 'sanctoral',
+      id: 'vigil-of-st-lawrence',
+      name: 'Vigil of St. Lawrence',
+      rank: 'vigil',
+    });
+    expect(saturday.commemorations).toEqual([]);
+
+    // The Sunday's own resolution is exactly as if the vigil didn't exist.
+    expect(sunday.winner).toEqual({ kind: 'temporal', id: 'post-pentecost-11' });
+    expect(sunday.commemorations).toEqual([]);
+
+    // St. Lawrence's own day (Monday) is unaffected by the backward transfer.
+    expect(monday.winner).toEqual({
+      kind: 'sanctoral',
+      id: 'st-lawrence',
+      name: 'St. Lawrence, Martyr',
+      rank: 'duplex-2-classis',
+    });
+  });
+});

tests/calendar/vespers.test.ts

@@ -33,8 +33,10 @@ describe('resolveEveningDay', () => {
     // Duplex I classis.
     const day = resolveEveningDay('2026-08-14');
     expect(day.date).toBe('2026-08-15');
-    const winner = day.occurring.find((f) => !f.commemorated);
-    expect(winner?.id).toBe('assumption');
-    expect(winner?.vespersFrom).toBe('firstVespersOfTomorrow');
+    expect(day.winner.kind).toBe('sanctoral');
+    if (day.winner.kind === 'sanctoral') {
+      expect(day.winner.id).toBe('assumption');
+      expect(day.winner.vespersFrom).toBe('firstVespersOfTomorrow');
+    }
   });
 });

tests/calendar/weekday.test.ts

@@ -31,10 +31,11 @@ describe('weekdayOf', () => {
 });
 
 describe('resolveDay', () => {
-  it('stubs season and occurring until milestone 4', () => {
+  it('resolves a plain Sunday with no occurring feast', () => {
     const day = resolveDay('2026-08-09');
     expect(day.date).toBe('2026-08-09');
     expect(day.weekday).toBe('sunday');
-    expect(day.occurring).toEqual([]);
+    expect(day.winner).toEqual({ kind: 'temporal', id: 'post-pentecost-11' });
+    expect(day.commemorations).toEqual([]);
   });
 });