DocumentCatalogue owns a set of entries and answers questions about them — search, count,
latest, names, types, stats, date span. It returns data and renders nothing.
Why it is its own package
It is a leaf. It depends on @repo/utils/time and lodash, and on nothing else — no database, no
EMR adapters, no agent framework. Both @repo/legacy and @repo/ai-agents consume it, so it
cannot live in either without one of them importing the other sideways.
It was born inside @repo/legacy, which opens a database connection at import time. That forced a
./chart-review/document-catalogue subpath export whose entire purpose was to reach the pure
module without waking the impure package around it. Moving it out deleted that workaround.
Invariants
Latest is the most recent DATED document. Undated ones sort last, so reading off the end of
the list returns an arbitrary document rather than the one asked for.
The week convention comes from the question, never from the data. A count exact under
Sunday–Saturday is wrong under Monday–Sunday, so a guess is a confidently wrong answer.
Drift runs one way. A document is recorded on or after whatever it is about, so a document
dated by its recorded day can only belong EARLIER than its date says — which is what makes the
uncertainty reportable instead of merely admitted.
Counting is not a selection concern. Selection decides which documents are in scope; what
falls in which week is arithmetic done afterwards, over the set it was given.
A title's trailing date is a date. The separator is required, so Note 2026-03-16 keeps its
whole name — without one there is no telling a date from a version or an ID.