fix(core): keep calendar-edge dates from failing a note's index

@effective:9999-12 constructed date(10000, 1, 1) and raised, and nothing
in the chain caught it: not the qualifier reader, not the observation
parser, not entity_parser. A note whose second observation carried that
qualifier failed the whole document parse — its other observations and
all its relations went with it.

Auditing the rest of the successor arithmetic found a worse instance the
report did not name: _instant_value calls astimezone(UTC), which raises
OverflowError when the offset shift crosses the calendar edge.
OverflowError is not a ValueError, so it escaped even the existing
except clause, and the same bounds reach the search router — where
ValueError maps to 400 and this was a 500. Three spellings were
reachable, including an underflow at 0001-01-01.

Terminal periods now render as the unbounded range they represent
(@effective:9999 -> [9999-01-01,), @effective:9999-12 ->
[9999-12-01,)); a year beyond the calendar stays content, and an instant
that leaves the calendar in UTC is refused at the bound rather than
thrown. The other six arithmetic sites were audited and are safe, each
for a stated reason.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/markdown/temporal_qualifier.py

@@ -248,7 +248,9 @@ def _truncation_reason(point: str, valid_during: TemporalRange) -> str | None:
 
     A bounded span is how a coarse point announces itself: `parse_authored_point` closes
     a year or a month at its successor and leaves a day or a moment open, so
-    `upper is None` *is* "this names a specific day".
+    `upper is None` *is* "this names a specific day". The one period with no successor
+    to close at -- December 9999 -- is left open too, and so reads here as a day; no word
+    resolves to it, so the guard never sees that shape.
     """
     if point[0].isdigit():
         return None if len(point) >= _MIN_NUMERIC_POINT_WIDTH else "is narrower than a year"

src/basic_memory/temporal.py

@@ -126,16 +126,26 @@ def _canonical_date(bound: str) -> str:
         raise TemporalQualifierError(f"not a calendar date: {bound!r}") from exc
 
 
-def _instant_value(moment: datetime) -> str:
+def _instant_value(moment: datetime) -> str | None:
     """Render one moment as the canonical fixed-width UTC instant.
 
     A naive moment is read as UTC rather than refused. That is the house convention for
     every other naive datetime in the codebase, and it is what lets an author write
     `2026-07-27T18:42:00` without learning RFC 3339's offset syntax first.
+
+    None means the moment has no UTC rendering: shifting it by its offset carries it off
+    the calendar, as `9999-12-31T23:59:59-05:00` does into year 10000. Reported the way
+    `_next_calendar_day` reports its own edge -- each caller decides what running off the
+    calendar means for it -- rather than raised, so the overflow can never escape as a
+    bare `OverflowError` and fail a whole note's parse.
     """
     if moment.tzinfo is None:
         moment = moment.replace(tzinfo=UTC)
-    return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
+    try:
+        utc = moment.astimezone(UTC)
+    except OverflowError:
+        return None
+    return utc.strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
 
 
 def _canonical_instant(bound: str) -> str:
@@ -151,7 +161,12 @@ def _canonical_instant(bound: str) -> str:
         moment = datetime.fromisoformat(bound.upper())
     except ValueError as exc:
         raise TemporalQualifierError(f"not a valid timestamp: {bound!r}") from exc
-    return _instant_value(moment)
+    value = _instant_value(moment)
+    if value is None:
+        raise TemporalQualifierError(
+            f"timestamp bound leaves the calendar when converted to UTC: {bound!r}"
+        )
+    return value
 
 
 def canonical_bound(bound: str, axis: TemporalRangeAxis) -> str:
@@ -478,12 +493,33 @@ def _date_data_parser(date_order: DateOrder) -> "DateDataParser":
     )
 
 
-def _calendar_span(lower: date, upper: date) -> TemporalRange:
-    """The half-open calendar period `[lower,upper)`."""
+def _next_month_start(year: int, month: int) -> date | None:
+    """The first day of the month after `year`-`month`, or None past the calendar's end.
+
+    Only December 9999 has no successor month; year 10000 is not a date `datetime` can
+    hold. Reported as None for the same reason `_next_calendar_day` reports its own
+    edge: the caller decides what running off the end of the calendar means for it.
+    """
+    if month < 12:
+        return date(year, month + 1, 1)
+    if year == date.max.year:
+        return None
+    return date(year + 1, 1, 1)
+
+
+def _calendar_span(lower: date, upper: date | None) -> TemporalRange:
+    """The half-open calendar period `[lower,upper)`, unbounded when it runs to the end.
+
+    A period whose successor is off the calendar needs no upper end: nothing follows
+    9999-12-31, so `[lower,)` holds exactly the days `[lower,successor)` would have. It
+    is the same equivalence `TemporalRange` applies to an inclusive upper bound on the
+    last date, and it is why December 9999 is a period this reader can express rather
+    than one it fails on.
+    """
     return TemporalRange(
         axis=TemporalRangeAxis.DATE,
         lower=lower.isoformat(),
-        upper=upper.isoformat(),
+        upper=None if upper is None else upper.isoformat(),
         lower_inclusive=True,
     )
 
@@ -533,24 +569,26 @@ def parse_authored_point(
     # the components `period` vouches for may be read off `moment`.
     match date_data.period:
         case "time":
+            instant = _instant_value(moment)
+            if instant is None:
+                # A moment that leaves the calendar in UTC names no storable instant,
+                # so it reads as no date at all -- the token stays content.
+                return None
             return TemporalRange(
                 axis=TemporalRangeAxis.INSTANT,
-                lower=_instant_value(moment),
+                lower=instant,
                 lower_inclusive=True,
             )
         case "year":
-            if moment.year >= date.max.year:
-                # There is no January 1 after year 9999 to close the span with.
-                return None
-            return _calendar_span(date(moment.year, 1, 1), date(moment.year + 1, 1, 1))
+            # The month after December is the following January 1 -- except at year
+            # 9999, where there is none and `_calendar_span` leaves the span open at
+            # `[9999-01-01,)`, which is still exactly that year.
+            return _calendar_span(date(moment.year, 1, 1), _next_month_start(moment.year, 12))
         case "month":
-            first = date(moment.year, moment.month, 1)
-            next_month = (
-                date(first.year + 1, 1, 1)
-                if first.month == 12
-                else date(first.year, first.month + 1, 1)
+            return _calendar_span(
+                date(moment.year, moment.month, 1),
+                _next_month_start(moment.year, moment.month),
             )
-            return _calendar_span(first, next_month)
         case _:
             # Day precision, and any coarser calendar period dateparser resolves to a
             # specific day ("last week"): the day it named, onward.

tests/markdown/test_temporal_qualifier.py

@@ -697,6 +697,9 @@ def test_an_unknown_kind_with_an_unreadable_payload_is_left_alone():
         # A date that the calendar does not have.
         ("- [decision] @effective[2026-02-30,) Use Redis.", "@effective[2026-02-30,)"),
         ("- [decision] @2026-02-30 Use Redis.", "@2026-02-30"),
+        # A moment that leaves the calendar once it is shifted to UTC.
+        ("- [decision] @effective[9999-12-31T23:59:59-05:00,) Use Redis.", "@effective["),
+        ("- [decision] @effective:9999-12-31T23:59:59-05:00 Use Redis.", "@effective:"),
         # Trailing junk: one broken token, not a qualifier plus content.
         ("- [decision] @effective[2026-06-10,2026-07-27)x Use Redis.", "@effective["),
     ],
@@ -710,6 +713,50 @@ def test_a_payload_that_does_not_read_as_time_stays_content(line: str, kept: str
     assert observation.content.startswith(kept)
 
 
+# --- One qualifier never costs the note its index ---
+
+
+def test_a_qualifier_at_the_end_of_the_calendar_does_not_fail_the_note():
+    """Whatever a qualifier says, the rest of the note still parses.
+
+    `@effective:9999-12` used to build `date(10000, 1, 1)`; the `ValueError` escaped
+    `parse_authored_point` and `parse_temporal_qualifier` -- neither of which guards that
+    call -- into the markdown parser, so *the whole document* failed over one qualifier:
+    every other observation and relation on the page went with it. December 9999 is
+    representable as `[9999-12-01,)`, so it files like any other period, and the
+    instant beside it, which is not representable at all, is simply left as content.
+    """
+    content = "\n".join(
+        [
+            "## Observations",
+            "- [decision] @effective:9999-12 The cache layer will use Redis.",
+            "- [decision] @effective:9999 The contract holds all year.",
+            "- [decision] @effective[9999-12-31T23:59:59-05:00,) An unstorable moment.",
+            "- [note] An ordinary observation that must still index.",
+            "",
+            "## Relations",
+            "- relates_to [[Cache Layer]]",
+        ]
+    )
+
+    parsed = parse(content)
+
+    month, year, unstorable, ordinary = parsed.observations
+    [month_assertion] = month.temporal
+    [year_assertion] = year.temporal
+    assert str(month_assertion.valid_during) == "[9999-12-01,)"
+    assert str(year_assertion.valid_during) == "[9999-01-01,)"
+    assert month.content == "The cache layer will use Redis."
+    assert year.content == "The contract holds all year."
+    # Unreadable, so never peeled: the line keeps its exact text and reports nothing.
+    assert unstorable.temporal == []
+    assert unstorable.temporal_error is None
+    assert unstorable.content == "@effective[9999-12-31T23:59:59-05:00,) An unstorable moment."
+    # The rest of the note is what the crash used to take with it.
+    assert ordinary.content == "An ordinary observation that must still index."
+    assert [relation.target for relation in parsed.relations] == ["Cache Layer"]
+
+
 def test_qualifier_with_nothing_to_qualify_stays_content():
     """Peeling it would leave an empty observation, which the plugin drops outright."""
     observation = _observation("- [decision] @effective[2026-06-10,2026-07-27)")

tests/test_temporal.py

@@ -10,7 +10,7 @@
   of the codebase applies to naive datetimes.
 """
 
-from datetime import date, datetime, timedelta
+from datetime import datetime, timedelta
 
 import pytest
 
@@ -138,6 +138,25 @@ def test_timestamp_shaped_bound_on_a_date_that_does_not_exist_is_refused():
         canonical_bound("2026-02-30T10:00:00Z", INSTANT)
 
 
+@pytest.mark.parametrize(
+    "bound",
+    [
+        "9999-12-31T23:59:59-05:00",  # 10000-01-01 in UTC
+        "0001-01-01T00:00:00+05:00",  # year 0 in UTC
+    ],
+)
+def test_instant_bounds_that_leave_the_calendar_in_utc_are_refused(bound: str):
+    """Normalizing to UTC *moves* a moment, and the move can run off the calendar.
+
+    Refused as a `TemporalQualifierError` like every other unreadable bound, which is
+    what makes it survivable: `datetime.astimezone` signals this with `OverflowError`,
+    and an `OverflowError` is not a `ValueError`, so it slipped past every handler above
+    -- failing a whole note's parse, or a whole search request, over one bound.
+    """
+    with pytest.raises(TemporalQualifierError, match="leaves the calendar"):
+        canonical_bound(bound, INSTANT)
+
+
 # --- TemporalPoint ---
 
 
@@ -359,16 +378,58 @@ def test_text_that_names_no_date_reads_as_nothing(written: str):
     assert parse_authored_point(written) is None
 
 
-def test_a_year_with_no_successor_is_unread():
-    """Year 9999 has no January 1 after it to close the span with."""
-    assert parse_authored_point("9999") is None
-    # The year before it still resolves, so the guard is the calendar edge, not 4 digits.
-    assert parse_authored_point("9998") == TemporalRange(
-        axis=DATE,
-        lower=date(9998, 1, 1).isoformat(),
-        upper=date(9999, 1, 1).isoformat(),
-        lower_inclusive=True,
-    )
+@pytest.mark.parametrize(
+    ("written", "literal"),
+    [
+        # The last year and the last month have no successor to close at, so the
+        # canonical form for them is unbounded -- exactly as it is for an inclusive
+        # upper bound on the last date.
+        ("9999", "[9999-01-01,)"),
+        ("9999-12", "[9999-12-01,)"),
+        # The last day was always open-ended, like every other day.
+        ("9999-12-31", "[9999-12-31,)"),
+    ],
+)
+def test_periods_at_the_end_of_the_calendar_run_to_the_end_of_it(written: str, literal: str):
+    """Unbounded above loses no days: nothing follows 9999-12-31.
+
+    `[9999-12-01,)` holds exactly the days a closed `[9999-12-01,10000-01-01)` would --
+    and year 10000 is not a date Python can build. Constructing it raised `ValueError`
+    straight through `parse_authored_point` and `parse_temporal_qualifier` into the
+    markdown parser, failing the *whole note* over one qualifier, which is the one thing
+    the qualifier contract promises can never happen.
+    """
+    span = parse_authored_point(written)
+
+    assert span is not None
+    assert str(span) == literal
+    assert span.is_empty is False
+
+
+@pytest.mark.parametrize(
+    ("written", "literal"),
+    [("9998", "[9998-01-01,9999-01-01)"), ("9999-11", "[9999-11-01,9999-12-01)")],
+)
+def test_the_period_before_the_calendar_edge_still_closes(written: str, literal: str):
+    """The open upper end is the calendar's edge, not "four digits" or "December"."""
+    span = parse_authored_point(written)
+
+    assert span is not None
+    assert str(span) == literal
+
+
+def test_a_year_beyond_the_calendar_is_unread():
+    """Year 10000 is not a date at all, so the token names nothing and stays content."""
+    assert parse_authored_point("10000") is None
+
+
+def test_an_authored_instant_that_leaves_the_calendar_in_utc_is_unread():
+    """The flexible reader has no bound to refuse, so it reads no date at all.
+
+    Its contract is None-for-unreadable, not an exception: `parse_temporal_qualifier`
+    does not guard this call, so anything raised here fails the note.
+    """
+    assert parse_authored_point("9999-12-31T23:59:59-05:00") is None
 
 
 # --- TemporalRange normalization ---