lectio.git/internal, branch perf/hoist-date-independent-work

perf(calendar): precompute the EF occupancy index alongside the transfer plan

2026-08-24T20:02:39Z

The prior commit (ea6e598) memoised efTransferPlan but left the SAME occupiedByClass1/Or2 O(len(merged)) scan pattern in a second place: transferIfImpededEF's own fallback path, called from computeEF once per day for every class-1 candidate the (now cached) plan does not resolve -- confirmed by CPU profile, not assumed: computeEF.func1 (the old occupiedByRank closure) was ~62% of BenchmarkDays7EF's total time, almost all of it inside buildCelebration, called from BOTH efTransferPlan internally AND this second, uncached site. Before optimising, established precisely what "occupied" depends on, per the coordinator's warning that occupancy might genuinely mutate during planning (efTransferPlan's own `claimed` map suggested as much). It does not: occupiedByRank asks only "does some OTHER entry's ORIGINAL, untransferred date (buildCelebration + celebrationDate, which never considers a transfer) equal d" -- a pure function of (merged content, year, sel) alone, identical to what the transfer-plan cache already keys on. `claimed`, by contrast, genuinely mutates during one planning pass (it tracks which TARGET days a transfer walk has already assigned) and is NOT part of occupiedByRank's computation at all -- it remains computed fresh inside efTransferPlan every call, untouched by this change. These are independent, not the same thing wearing two names: efTransferPlan's own forward-walk loop already checks both, plus a third condition (the target day's own temporal class), as separate disjuncts. Given that, an occupancy INDEX -- not a second cache, and not a "we already know the answer" shortcut derived from plan's absence (which would have been correct for the transferIfImpededEF fallback's own control flow ONLY by coincidence: it ignores the unconditional All Souls Sunday-transfer special case that runs before the class-1 check on ANY rank, so a shortcut skipping straight past it would misfire the moment a user overlay retagged All Souls class-1, however unlikely on shipped data) -- is the safe fix: buildEFOccupancyIndex does the same merged-scan ONCE, into date -> []{slug, rank}, and .occupied does the exact O(1)-ish lookup + tiny-list filter occupiedByRank always computed, just precomputed. transferIfImpededEF's own signature, control flow and All Souls handling are completely unchanged; only what its two closure parameters read from changed. The index shares the transfer-plan cache's existing key (year, Selection, SHA-256 of merged) rather than adding a new one -- both are pure in exactly those three inputs, built in the same pass, so one key correctly covers both. Only the plan is copied per call (clonePlan); the index, which can hold one entry per merged slug (~330 on shipped data), is returned uncopied and documented immutable-after-construction -- safe under Go's concurrent-read guarantee since nothing anywhere writes to a returned index. New TestEFOccupancyIndexDetectsSameDateClass1Collision covers a path no existing test reached: two class-1 SANCTORAL entries sharing one ORIGINAL date (St Joseph/the Annunciation, covered by the prior commit's tests, collide via HOLY WEEK's temporal precedence on DIFFERENT dates, never with each other). A synthetic overlay (Compute's own public API, same style as the existing tests) puts two class-1 entries on the same otherwise-ordinary date: alone, either is simply observed; both together, RG 97/98 transfer both forward and the shared date reverts to its temporal office. Mutation-proved: dropping the index's exceptSlug self-exclusion (reverted after) made the test fail immediately -- every class-1 entry saw itself in the index and wrongly self-impeded, even the single-entry case. TestEFTransferPlanCacheConcurrentUse gained a third, disjoint key exercising this same collision path from goroutines alongside the two existing ones; `go test -race` on the whole package is clean. Benchmarked (interleaved before/after, same method throughout this branch): BenchmarkDays7EF drops from ~46-48ms (the prior commit's own plan-cache-only state) to ~15-18ms/op (allocs 208639 -> 98727, -53%; bytes 16.1MB -> 4.2MB, -74%) -- roughly a further 3x, ~4.6x cumulative against the original ~74ms. BenchmarkDaysWeek (OF, which never touches any of this) is unaffected: ~4.9-5.9ms/op both before and after, with byte-for-byte identical allocs/bytes in every run -- the ms-level wobble is machine noise, not a regression. A fresh CPU profile confirms the new remaining bottleneck precisely: writeSortedFields/hashMergedForPlan (the cache key's own SHA-256 of merged, ~330 entries) is now ~35% of total time, because it still runs on EVERY day (7x/week) to know whether a call is a cache hit, even though the work it gates now mostly isn't. Not fixed here: hoisting the key computation itself up to mobile.Days's batch level (mirroring the first commit on this branch, b6ee8f0) would need Compute's public signature to accept a precomputed key, a bigger surface change than this task's scope, reported rather than taken unilaterally. Output identity re-verified: the same 492-case sweep (both forms, both UI languages, all four corpora, the leap day/Triduum/Requiem/season- boundary dates, and the three Joseph/Annunciation years) is byte-identical (SHA-256-equal) before and after -- the same SHA-256 as the prior commit's own sweep, confirming zero output drift across the whole chain. go test ./... and make ci (both build tags, oracle/differential suite included) are green; go test -race on the whole internal/calendar package is clean.

perf(calendar): memoise the EF transfer plan across a shared calendar

2026-08-24T19:42:48Z

computeEF calls efTransferPlan once per day, but the plan is pure in (year, the merged sanctoral content, Selection) and identical for every day sharing those three -- e.g. every date in one mobile.Days week. Rebuilding it per day was a real cost: efTransferPlan walks every merged entry looking for class-1 candidates, and for each one it considers, occupiedByClass1/Or2 (an occurrence check it also uses) walks merged AGAIN -- confirmed by CPU profile, not just by reading the code (github.com/lukaszkasprzak/lectio/internal/calendar.computeEF.func1, the occupiedByRank closure, at ~62% of BenchmarkDays7EF's total time before this fix, almost all of it inside buildCelebration). efTransferPlanCached (transfer_plan_cache.go) wraps efTransferPlan with a small, bounded, thread-safe LRU (container/list + sync.Mutex, capped at 64 entries -- gomobile may call in from multiple goroutines, and an unbounded map keyed by year would grow as a user scrolls through decades). The cache key is (year, Selection, a SHA-256 of merged's full content): merged is a map, so it cannot be a map key field itself, and Go's randomised map iteration order means two calls with identical content can visit it differently, so the hash sorts slugs and, within each entry, its Fields/Variant keys before hashing, and covers every field of every entry -- not just Rank/Date, the ones efTransferPlan's own read path happens to touch today, because which entries even qualify as class-1 is itself computed from that data, and occupiedByClass1/Or2 scan ALL of merged, not just the class-1 subset. Selection is included even though EF date resolution ignores it today (resolveDate never reads its sel parameter) -- keying on it costs nothing (four small strings) and protects a future change from silently poisoning a cache that never accounted for it. The returned map is always a fresh copy (clonePlan), never the cached instance, so sharing it across goroutines needs no further synchronisation. Verified the key is complete rather than trusted: with the content hash temporarily dropped from the key (mutation test, not committed), TestEFTransferPlanCacheInvalidatesOnOverlay failed immediately -- a plan warmed for the shipped 2008 calendar was wrongly served back for the same year with a user overlay applied (the Annunciation suppressed, which changes where the RG 96(a)/97/98 collision sends St Joseph: 31 March instead of 1 April, empirically confirmed against the pre-cache code before the test was written). TestEFTransferPlanCacheInvalidatesOnYear is a lighter companion covering the year field. TestEFTransferPlanCacheConcurrentUse hammers the cache from 12 goroutines across two different keys and reasserts correctness afterward; clean under `go test -race`. Benchmarked (interleaved before/after, same method as the readings.Prepare commit, to control for machine thermal drift): BenchmarkDays7EF drops from ~48-51ms to ~32-35ms/op (allocs 253810 -> 208639, -18%; bytes 28.1MB -> 16.1MB, -43%), roughly a third faster. BenchmarkDaysWeek (OF, which never calls efTransferPlan at all) is unaffected, ~3.5-4.1ms/op both before and after -- within noise, confirming this change is EF-only as intended. EF remains well outside OF's range (~32ms vs ~4ms), and a fresh CPU profile after this fix places the dominant remaining cost precisely: it is the SAME occupiedByClass1/Or2 pattern, but living OUTSIDE efTransferPlan -- transferIfImpededEF's own fallback path, called once per day for every class-1 candidate NOT already resolved by the (now cached) plan, i.e. the ordinarily-unimpeded ones (~15-20 of them), each triggering another O(len(merged)) scan. That call site was not part of what this task named, and memoising it is a materially different change (it is keyed per-candidate, not once per day), so it is reported here rather than folded into this commit. Output identity re-verified: a 492-case sweep of mobile.Day/mobile.Days (both forms, both UI languages, all four corpora, a leap day, the Sacred Triduum, a Requiem day, Christmas/Pentecost/Assumption/All Souls windows, and the three Joseph/Annunciation transfer-collision years this fix specifically touches -- 2008, 2035, 2046) produced byte-identical (SHA-256-equal) JSON before and after. go test ./... and make ci (both build tags, oracle/differential suite included) are green.

perf(readings): stack calendar layers and load the book table once per Days call

2026-08-24T14:35:01Z

mobile.Days (dlectio's 7-day calendar view) called readings.Load once per date. Load's offlineLoad re-ran caldata.Stack (parses the embedded calendar INI, plus any user calendar layer) and bible.LoadBookTable (parses the embedded books.ini, plus any user override) on every call, even though neither depends on the date -- only on cfg.Selection().Form and cfg.Use, which mobile.Days holds fixed across its whole loop. Verified before changing anything: isolated benchmarks put Stack+ LoadBookTable at ~1.1ms/call (OF) and ~1.6ms/call (EF) -- real INI parsing and, for a user override, file I/O -- and for the OF form that redundant work was ~67% of a 7-day view's total time. Load gains a Prepared value (the layer stack + book table) and a Prepare/LoadWith pair: Prepare builds a Prepared once, LoadWith reuses it across dates. Load itself is unchanged, still calling Prepare on every invocation -- every existing caller keeps its current behaviour untouched. mobile.Days now Prepares once and loops LoadWith; mobile.Day picks up the same fix for its own two same-cfg Load calls. Benchmarked (interleaved before/after pairs, to control for machine thermal drift): the OF 7-day view (BenchmarkDaysWeek) drops from ~11.5ms to ~6.4ms/op (allocs 53359 -> 16347, -69%), an EF 7-day view (BenchmarkDays7EF) from ~74ms to ~66-73ms/op (allocs 299204 -> 253815, -15%; the EF form's per-day calendar computation dominates its total cost far more than OF's does, so the fix's share of the win is smaller there), and a single Day call (BenchmarkDay1) from ~4.3ms to ~2.9ms/op (allocs 15357 -> 9192, -40%). Output identity verified separately (not part of this diff): a 288-case sweep of mobile.Day/mobile.Days across both forms, both UI languages, all four corpora, a leap day, the Sacred Triduum, a Requiem day, and windows spanning Christmas/Pentecost/Assumption/All Souls produced byte-identical (SHA-256-equal) JSON before and after this change. New TestLoadWithAgreesWithLoad asserts LoadWith(Prepare(cfg), cfg, opts) equals Load(cfg, opts) for every case, so the fast path cannot silently drift from the slow one. go test ./... and make ci (both build tags, oracle/differential suite included) are green.

fix(ef): two I-class feasts can no longer transfer onto the same day

2026-08-18T15:33:20Z

RG 97/98 require a year's impeded I-class transfers to be resolved together. transferIfImpededEF resolved each one independently, so when an early Easter impedes both St Joseph (19 March) and the Annunciation (25 March), both walked to the Monday after Low Sunday -- and St Joseph, losing pickEF there, was observed on NO day of 2008, 2035 or 2046 at all. He appeared only as a commemoration in the Annunciation's tail. RG 96(a) settles it outright, and it is not a tie-break: the Annunciation transferred after Easter has a sedes propria -- "quando est transferendum post Pascha, transfertur, tamquam in sedem propriam, in feriam II post dominicam in albis". It claims the Monday by law; the rest queue in RG 98's order (table position, then the office impeded first) and walk around it. New efTransferPlan resolves the whole year's transfers as a set and hands each feast its target; transferIfImpededEF keeps the single-candidate walk and All Souls. The stale doc comment recording this as a known unfixable limitation is replaced -- its reasoning argued RG 97/98 tie-breaks, when RG 96(a) decides the only collision the universal calendar actually produces. 2008-04-01, 2035-04-03, 2046-04-03 ef-easter-2-tuesday -> St Joseph Matches colitur on all three. Mutation-tested: bypassing the plan reddens the new test on all three years. fix(ef): 13 January's Baptism is omitted when Holy Family falls on it The Holy Family Mass propers, verbatim in both photographic scans of the 1962 Missal: "Si festum S. Familiae occurrerit die 13 ianuarii, Missa dicitur de festo S. Familiae, sine commemoratione Baptismatis D.N.I.C., et sine commemoratione dominicae." Sine commemoratione: the Baptism is omitted outright, not merely outranked, so the candidate is dropped rather than left in Others. Structurally the same answer RG 91 entry 14 gives (Festa Domini II classis: primum mobilia, deinde fixa), but the propers' rubric is the direct authority for the omission. lectio kept the Baptism as the observed office on all seven such years in 2005-2050 -- 2008, 2013, 2019, 2030, 2036, 2041, 2047 -- and never observed the Holy Family Mass on 13 January at all. It already had the Holy Family Mass on every other Sunday after Epiphany, so this was the one date it could not reach. 13 rows of the 16801-day differential fixture change; colitur agrees with all of them.

fix(ef): the ferias between Epiphany and the Sunday after it

2026-08-18T15:15:27Z

They repeat Epiphany's own Mass, Isa 60:1-6 / Matt 2:1-12. lectio gave them the Mass of the first Sunday AFTER Epiphany (Rom 12:1-5 / Luke 2:42-52), which belongs to the ferias that follow that Sunday, not to the ones before it. The two groups cannot be told apart by slug: both are ef-time-after-epiphany-1-, because the week numbering starts at the Sunday and the days before it fall in the same numbered week. So the split is made on the date, against the same anchor efWeek uses. Saturdays need no exclusion here -- an unoccupied Saturday in the window carries Our Lady's office and her Mass, and that check runs first. colitur reaches the same result by listing only the five non-Saturday weekdays. 7, 9 and 12 January 2026 now all match colitur, the 12th being the boundary case: it follows the Sunday of the 11th and correctly keeps Rom 12:1-5.

fix(ef): three saints with proper Masses had no readings at all

2026-08-18T15:11:04Z

Francis of Paola (2 April), Thomas Aquinas (7 March) and John of God (8 March). Unlike the nine added in the previous commit these are NOT Common- routed -- the Missal prints a proper Mass for each -- they simply had no reading in this repository and resolved nothing. John of God is the one worth a note: his Epistle, Ecclus 31:8-11, is also the Common of a Confessor not a Bishop I, which makes him look Common-routed. He is not; the Gospel differs and the Missal prints the Mass at his own date. With these, every day of 2005-2050 resolves a reading. Nothing in that range comes back empty any more, where before there were four such days.

feat(ef): the Masses of saints that come from a Common

2026-08-18T15:06:28Z

Nine saints have no proper Mass in the Missal. Its rubric at each one's own date names a Common -- "Missa Statuit, de Communi Confessoris Pontificis I loco", "Missa Iustus ... II loco", and so on -- and only the Oratio is proper. lectio has no Commons concept, so those days resolved no reading at all. Benedict, Frances of Rome, Gregory the Great, Isidore of Seville, Patrick, Perpetua & Felicity, Vincent Ferrer, Ubaldus and Didacus. The readings are written per saint rather than by adding a Commons abstraction. Each Common resolves to exactly one first/gospel pair for the saint that names it, so a table plus an assignment layer would buy indirection and nothing else here; if a future saint needs a Common's OTHER formulary, that is when the abstraction earns its place. They go into the generator's missalOverrides table like the rank and colour corrections, because missalemeum supplies these days with whatever it supplies them and a regeneration would otherwise leave nine saints mute. The table learned two new field names to carry them. Four are pinned in TestTridentineMissalOverrides. Citations are colitur's, verified there against both photographic scans and the rendered page images; its data/ef/commons.sexp header records the three-source method and the per-value evidence.

feat(ef): the Most Holy Name of Jesus, and the ferias of 2-5 January

2026-08-18T15:02:47Z

RG 17(a): "festum Ss.mi Nominis Iesu, celebrandum dominica quae occurrit a die 2 ad 5 ianuarii, secus die 2 ianuarii." The Most Holy Name is kept on the Sunday falling 2-5 January and, when no Sunday falls in that window, on 2 January instead. lectio built neither shape, so the day was an ordinary Sunday within the octave and read Gal 4:1-7. The FALLBACK matters more than it looks. The window is four days wide, so in about three years in seven no Sunday lands in it -- in those years there was no Holy Name office at all, a missing II-class feast rather than a misnamed one. The test pins both shapes, checks the fallback does NOT also fire in a year where the Sunday carries the feast, and asserts across 2005-2050 that every year gets it exactly once by one shape or the other. Separately, the ferial days of that window get their own Mass. The Missal's rubric at the feast says it directly: "Diebus ferialibus a 2 ad 5 ianuarii Missa dicitur ut die 1 ianuarii" -- the Circumcision's Mass, Titus 2:11-15 / Luke 2:21. They had been falling through to the Sunday within the octave. Ferial only, and the exclusions are the interesting part: the Sunday carries the Holy Name and its own Mass, and an unoccupied Saturday carries Our Lady's office and hers. 3 January 2026 is such a Saturday and correctly reads Titus 3:4-7, not 2:11-15 -- which works because the BVM check runs first. All four days of 2-5 January 2026 now match colitur.

fix(ef): Passion week and Holy Week are two weeks, not one

2026-08-18T14:49:03Z

efWeek had no Passiontide case, so both weeks fell through to 0 and every day of Holy Week took the slug of its Passion-week namesake: ef-passiontide-0- monday served both Passion Monday and Holy Monday. The two weeks therefore shared one set of readings and Holy Week could not have its own -- Good Friday was reading Passion Friday's Mass. Numbered from Passion Sunday now, so the weeks are 1 and 2 and the slugs distinguish them. The six ef-passiontide-0-* sections are replaced by colitur's twelve rather than renamed, and the reason is worth recording: they were not simply Passion week's Masses. The Tuesday section carried HOLY Tuesday's (Jer 11:18-20 with the Passion according to Mark), which was Passion Tuesday's only by the same collision -- colitur documents that specific mix-up and its own correction of it. Renaming 0 to 1 would have kept the wrong Mass on Passion Tuesday while looking like a clean migration. All twelve are colitur's, verified there against both photographic scans. All six days of Holy Week now match colitur, and so does Passion Tuesday.

fix(ef): twelve days were serving the preceding Sunday's Mass

2026-08-18T14:46:47Z

Corpus Christi, the Sacred Heart, and the ferias of the first week after Epiphany and the first week after Pentecost had no lectionary entry, so each fell through the walk-back and read the Mass of the Sunday before it. Corpus Christi -- a I-class feast with one of the best-known formularies in the Missal -- was reading Trinity Sunday's. RG 299 is why the first weeks need naming where the others do not: "Item propriam Missam habent omnes feriae..." -- those ferias have proper Masses, and the walk-back that serves the rest of the year correctly is wrong for them. Citations are colitur's, verified there against both photographic scans. They were added rather than derived: a comparison of the two lectionaries found the 110 shared slugs agree on EVERY citation, so the divergence was entirely entries lectio lacked, not entries it had wrong. Twelve of the 43 colitur has and lectio lacked. The other 31 name days lectio calls something else, so adding them verbatim would be dead data; those need the slug question answered first and are deliberately not touched here.