# fn-18.2 Frontmatter date sort for temporal queries

## Description

Frontmatter date sorting for temporal queries.

Scope:

- Parse frontmatter date fields into canonical doc_date.
- Store doc_date in DB + expose in APIs.
- Use doc_date for newest/latest temporal ranking; fallback to file modified.
- Ensure MCP + CLI use same ordering.

## Acceptance

- field precedence list defined (date, published, published_at, created, updated) or explicit config
- frontmatter date parsed to UTC timestamp, invalid dates ignored
- newest/latest sorts by doc_date when present, else by source modified
- MCP + CLI query results show consistent ordering
- tests or fixtures cover at least 2 frontmatter date formats

## Done summary

Implemented frontmatter date canonicalization + recency-intent ordering across retrieval paths.

Delivered:

- Canonical doc-date parsing in ingestion:
  - Date precedence: `date`, `published`, `published_at`/`publishedAt`, `created`, `updated`.
  - Parses date-only and timezone datetime forms; strips quoted scalar wrappers.
  - `INGEST_VERSION` bumped to `4` so existing docs are backfilled on sync.
- Recency sort behavior:
  - Added shared temporal helpers for recency intent detection and timestamp fallback.
  - Queries containing recency intent (`latest`, `newest`, `recent`, etc.) sort newest-first.
  - Ordering key: canonical frontmatter date first, fallback to source modified time.
  - Applied consistently in BM25 (`search`), vector (`vsearch`), and hybrid (`query`/`ask`) pipelines.
- API exposure:
  - Search result source metadata now includes `documentDate` when available.
  - FTS adapter now selects and propagates frontmatter date from DB.
- Tests:
  - Added/extended tests for recency sort in BM25/vector/hybrid pipelines.
  - Added ingestion tests for date precedence and multiple date formats.

## Evidence

- Commits:
- Tests:
- PRs:
