trail-mate/docs/development/agenda-implementation.md

# Agenda implementation notes

## Scope and status

The authoritative requirements are in
`docs/specs/Agenda_Calendar_Implementation_Specification.md`.
This is a technical implementation record, not an acceptance report.
The sections below are chronological checkpoints, not the current storage design.
Registration, the main UI, reminder logic and local waypoint save/select have
implementation and native-test coverage. Internal-flash storage is not a supported
Agenda backend. SD lifecycle integration, device validation and final acceptance remain
incomplete. Earlier successful builds do not establish SD-backed acceptance.

### Current storage contract

- Agenda events and saved local waypoints reside on the SD card only.
- No available application-owned SD card means no event/waypoint operations or
  Agenda reminder delivery. Cached rows or scheduled reminders do not provide
  an offline mode.
- Removal or ownership loss invalidates storage readiness and cached results;
  incomplete writes must not be reported successful. Remount requires store
  validation and rebuilding queries/reminders from that card. Do not silently
  save a retained draft to a different card.
- Use the existing shared SD runtime. SPI and SDMMC retain its existing access
  policies; no device-specific Agenda storage path is permitted.
- Internal FFat/LittleFS/NVS are not record-store fallbacks. Agenda must not
  format internal flash or the SD card to recover an error.

The current UI media-loss policy ends the active Agenda editing/navigation
session and discards its unsaved draft, pending UI actions and suspended return
context. An active Map tree is closed before its request storage is released.
An active Agenda returns to the unavailable list; a suspended Agenda is not
opened over another application. Revalidation starts a new session rather than
restoring old-card IDs. Native LVGL tests cover active Map, queued Save and
suspended-editor invalidation on both display geometries. This establishes the
response to a storage-loss signal, not physical card-removal detection.

The SD record adapter binds to the media session validated by its owner. The
shared runtime checks the expected session under its filesystem lock before
opening a file or renaming a staged file. Closing and reopening files within a
store operation therefore cannot implicitly adopt a replacement card. The native
`tests/sd_record_io` fixture compiles the production adapter and injects replacement
at open and publication boundaries. Its simulated runtime verifies adapter token
propagation; it does not prove hardware detection or runtime lock behavior.

Internal-flash references in historical checkpoints below describe superseded
work, not instructions to retain or repair that backend. No SD migration or
on-device success is claimed by this documentation update.

## Map location annotations

Event locations remain part of `/agenda/events.dat`; there is no exported POI
file or duplicate waypoint record. Selecting a saved waypoint copies its location
into the event, so subsequent waypoint edits do not silently move the event.

The target supplies an optional `MapMarkerBinding` through the catalog and Map
route. `IMapMarkerSource` exposes status and a streamed read-only visitor; the
shared map renderer knows neither Agenda storage paths nor recurrence rules.
Other map previews do not opt into this binding.

All saved active records with locations are candidates, including past events.
At most 32 annotations are retained, ordered by viewport visibility, distance
from its center, then stable event ID. Empty and deleted records are excluded.
Unended event titles are red, ended titles gray; an invalid clock is neutral gray.
Recurring records project their next or ongoing occurrence without storing copies.
The event detail preview starts at zoom 16.

The viewport owns a compact cache and one aligned record scratch buffer. On ESP
the target allocator requires PSRAM and never falls back to internal SRAM.
The cache is released on viewport destruction or storage loss. Failed allocation
or reads clear/defer annotations without disabling the base map; retries are
throttled. A failed scan never publishes a partial result.

A 64-pixel query margin avoids rescanning during small pans. Overflowed queries
are reselected after movement so off-screen entries cannot starve visible ones.
Revision, storage readiness, clock validity, time transitions, zoom, coordinate
system and viewport coverage invalidate the cache. Drag previews only translate
annotations. Draw callbacks never access storage. The existing overlay layer
draws markers and titles directly, without per-event LVGL objects; LVGL still
uses transient draw-task allocations under the platform's normal allocator.

## Repository audit (2026-09-21)

| Product | Target profile | Declared / resolved UX pack | Page manifest | Layout |
| --- | --- | --- | --- | --- |
| Pager, SX1262 / LR1121 builds | `tlora_pager` | `pager_compact` / `compatibility` | `pager_compact_manifest` | `pager_compact`, 480 x 222 |
| T-Deck | `tdeck` | `deck_full` / `compatibility` | `deck_full_manifest` | `deck_wide`, 320 x 240 |
| Wio Tracker L2 | `wio_tracker_l2` | `deck_touch` / `deck_touch` | `deck_full_manifest` | `deck_wide`, 320 x 240 |

Sources: `modules/product_composition/src/target_profile.cpp` and
`target_ux_binding.cpp`. Input must use the corresponding UX bindings; Wio is
touch-only, whereas Deck has keyboard/trackball as well. Resolution is not an
input capability test. Watch also resolves to `compatibility`; adding Calendar
unconditionally to that pack would incorrectly widen target scope.

Current manifest counts: Pager 6, Deck 9. Current resolved screen counts:
compatibility 10, deck_touch 9. Both screen and binding registries have capacity
16. Calendar does not justify expanding either array. The separate app catalog
also has capacity 16 and must be checked with all optional apps enabled.

Registration traverses PageId, manifest, UX pack, ScreenId, MenuScreenId,
screen/menu adapter, binding factory and catalog. Inspecting or changing only
`app_catalog_builder.cpp` is insufficient. Non-target packs must remain unchanged.

### Ownership and existing integration points

- Embedded app composition is under `apps/esp32_lvgl/src`. Arduino startup and
  loop runtimes are separate. Agenda services/adapters will be owned here, not
  by the page or `AppServicesBundle`.
- `PresentationWorkspace` is the existing typed graph of externally owned
  models. Agenda source/sink contracts belong in `ui_presentation`.
- Tracker's shell/runtime/components/input/state files establish the current
  page split. Existing Tracker filesystem calls are not a precedent for new
  Agenda UI I/O.
- Global interruption precedent: `reticulum_call_overlay::tick()` is driven by
  the app loop independently of an open page. Agenda reminders need equivalent
  lifetime and safe focus restoration, with no interruption of an existing
  modal until it can be presented safely.
- Clock: `sys::epoch_seconds_now()` and `platform::ui::time` expose UTC and the
  configured timezone. The platform time runtime considers epochs before 2020
  invalid. Calendar arithmetic must not depend on LVGL or Arduino.
- Storage must use the shared SD runtime, with logical event path
  `/agenda/events.dat` relative to the card. The unrelated internal `ffat`
  partition at `/fs` is not an Agenda backend. Reuse SD file/ownership APIs,
  not the chat database or NVS configuration store. Do not repartition or format.
- `MapWorkspaceModel` already owns viewport/tool actions; `gps_page_shell`
  accepts a `RouteSpec` with a host and projection. There is currently no
  SelectLocation mode in `MapToolKind`. Add a semantic selection/return contract
  to that workflow, not another map renderer. Preserve only the small editor
  draft while the map tree exists.
- A bounded saved-waypoint query is not exposed by the inspected Map workspace
  contract. Locate its authoritative saved-item source and add a bounded adapter
  before implementing the picker; the Team snapshot's vectors are not a suitable
  Agenda-owned database.
- Use the supplied `modules/ui_shared/src/ui/assets/agenda.c` for the catalog icon.

### Build ownership

Reviewed entrypoints: `apps/esp32_lvgl/CMakeLists.txt`,
`cmake/TrailMateUxPacks.cmake`, `cmake/TrailMateLinuxSources.cmake`,
`builds/esp_idf/ESP_IDF_COMPONENT_SOURCES.cmake`, and `scripts/platformio-pre.py`.
Portable tests should compile the same core sources. Build integration must be
explicit for each enabled product; Linux/GTK/ASCII/headless/watch are not newly
enabled products.

### Analysis limitation

GitNexus reported an index 53 commits behind HEAD. `npx gitnexus analyze` was
attempted and exited 1 after native parser worker timeouts, including the large
GPS runtime. Do not interpret absent graph results as proof of zero impact.
Run symbol impact queries before modifying existing symbols, supplemented by
current source/caller checks and regression tests.

## Verification still required

- Portable record validation, recurrence boundaries, bounded queries, scheduler
  simultaneous due events/snooze/clock changes.
- Fixed-slot persistence/reload, corrupted records, interrupted writes, full
  store, deleted-slot reuse; no whole-database cache.
- Full target registration/capacity tests and explicit excluded-target tests.
- Actual 480 x 222 and 320 x 240 LVGL render/input tests, localization, editor
  cancel/save, reminder while page closed, and map pick/return lifecycle.
- Size assertions and target RAM/build evidence, then hardware validation.

## Portable core checkpoint

Implemented in `modules/core_agenda` (not yet wired into firmware):

- Fixed 256-byte, little-endian, versioned/CRC-protected record codec; 64 slots.
- Single-record CRUD service; tombstones retain IDs and vacant slots are reused.
- Calendar arithmetic and daily/weekly/monthly/yearly occurrence calculation.
  Nonexistent dates are skipped (January 31 does not become February 28;
  February 29 recurs in the next leap year). Start/end values represent local
  calendar seconds; timezone conversion belongs to the platform clock adapter.
- Bounded sorted query with `(start,event_id)` pagination and explicit overflow;
  month occupancy uses a 32-bit mask. Corrupt rows are reported as degraded in
  agenda queries; write operations fail closed on unreadable slots.
- Reminder scheduler with one next candidate and one explicit snooze. Ordinary
  ticks perform no store scans. Same-time reminders are ordered by ID; closing
  one does not consume the others. An occupied presentation sink defers delivery.
  Startup/material clock corrections skip already-past triggers. A second
  concurrent snooze is rejected, not silently substituted; the renderer must
  surface this outcome. Snooze/dismiss state is runtime-only in V1.

Host CTest currently passes five executables: codec, CRUD, recurrence/query,
reminder scheduler, and calendar limits. Date round-trips cover every date from
1970 through 2400, including non-leap centuries. Host sizes: EventRecord 208 B,
AgendaPage 1048 B, ReminderScheduler 136 B, CivilTime 8 B, month mask 4 B. These
are structure sizes, not a claim about total embedded idle RAM or storage I/O.
Real filesystem recovery, platform clock/timezone binding, product registration,
LVGL rendering/input, map integration and hardware tests remain outstanding.

## Persistence checkpoint (superseded internal-flash backend)

At this historical checkpoint, `platform/esp/common/storage/AgendaFileStore`
implemented the slot port using standard file I/O over the mounted internal
filesystem. That backend is not compliant with the current SD-only contract.
The record layout uses two independently
CRC-protected 256-byte banks per logical slot, with slot identity and generation
inside the checksum. File size is 33,024 bytes (256-byte header + 64 dual-bank
slots). The RAM object is 488 bytes on the host. It opens files only for an
operation and retains no event table. New files are initialized via a separate
temporary file; existing invalid headers, truncated files and future versions
are reported rather than reformatted or downgraded.

The former internal-filesystem mount policy is obsolete and must not be used as
an implementation recipe. Storage preparation must require an available,
application-owned SD card and validate the Agenda directory without formatting
any medium. `AgendaClock` uses the existing timezone policy and ESP monotonic timer.

Seven host tests now pass, including actual temporary-file create/update/delete,
reopen, capacity, slot reuse, both-bank corruption, future-format refusal and
wrong-slot detection. Interrupted-record testing replaces every possible prefix
of a physical-bank update and verifies recovery of an old or new valid record.
The former internal-filesystem mount-policy tests do not establish compliance
with SD requirements. Verification must cover missing media, removal, ownership
transfer, validated remount and replacement cards. Record-bank recovery tests do
not prove whole-filesystem recovery from physical power loss; FAT metadata and
first-initialization failures still require device-level validation.

## Presentation and composition checkpoint

`AgendaWorkspaceModel` implements portable source/action contracts. A single
fixed command slot separates UI acceptance from durable completion; save/delete
are executed by the composition pump, not inside an LVGL callback. Failed writes
must leave the editor open with its draft. The CRUD service retains only a store
reference; its 208-byte operation scratch record is temporary rather than idle
state. Target stack depth still needs an embedded build check.

`AgendaComposition` owns the service, scheduler, workspace model, and small
reminder presentation bridge. Its store/clock dependencies belong to the target
root. The typed `PresentationWorkspace` gains two nullable pointers; no Agenda
service was added to `AppServicesBundle` or AppContext. Existing non-Agenda
workspaces remain unbound and keep their previous interactive-status behavior.
The bridge holds only reminder identity/timing, not an EventRecord or UI tree.
The shell controls whether new reminders may be delivered while another modal
owns input. Popup actions carry a presentation revision, checked both when
queued and when executed, so stale callbacks cannot dismiss another occurrence.

Nine host CTest executables pass. The added composition test exercises a draft
whose lifetime ends before reminder delivery, deferred presentation without
per-tick database reads, simultaneous reminders, snooze capacity, stale popup
actions, and withdrawal between enqueue and execution. The existing
`test_presentation_bundle_shape.cpp` was also compiled and run unchanged.

Current MinGW host sizes are AgendaComposition 456 B, reminder bridge 48 B,
and the aggregate of composition + real file-store object + test clock 976 B.
The aggregate has a compile-time `< 1024` assertion; it does not instantiate or
cache an in-memory production event table. The two workspace binding pointers
cost an additional 8 B on this host. Embedded object sizes, filesystem runtime
costs, task stacks, and device behavior remain to be measured.

The portable composition is implemented and tested, but firmware startup/loop
wiring, full target registration, LVGL pages/popups, localization, and map
integration are not yet complete. These host tests are not UI or device acceptance.

## Target registration and first renderer checkpoint

Calendar is declared only in `pager_compact_manifest` and `deck_full_manifest`.
WIO's existing DeckTouch pack projects the latter directly. Pager and T-Deck
now select manifest-backed compatibility packs: these preserve every existing
compatibility screen and append enabled manifest screens without duplicates.
They remain marked as transitional (`final_ux_pack_available == false`). The
shared compatibility pack is unchanged, so Watch and Tab5 do not inherit the
new page. No screen/binding array capacity was increased.

Verified chain: TargetProfile -> PageManifest -> selected UX pack -> ScreenId
-> MenuScreenId -> ScreenBindingRegistry (`calendar`). Resulting screen/binding
counts are WIO 10, Pager 11, T-Deck 11; other target profiles exclude Calendar.
The AppCatalog descriptor and target runtime wiring are still outstanding.

The first LVGL renderer now implements the bounded Agenda list, occurrence
detail, and confirmed asynchronous deletion. Sources/actions are injected in
the shell Host. Page state is allocated on enter and released on exit; it does
not own services or storage. Input callbacks only request transitions. A page
timer applies them after the input callback, and TopBar Back participates in
the same focus group as page controls. Pagination advances after the last
actually rendered row, including space consumed by date section headings.

Native LVGL tests compile the production page, shared TopBar, and layout code.
The host stubs only locale-pack/font fallback, board power, and input-group
binding. Tests render actual 480 x 222 and 320 x 240 RGB565 framebuffers and
generate `agenda-home-480x222.bmp` / `agenda-home-320x240.bmp` in the UI build
directory. They verify button bounds, Back focus traversal, deferred page exit,
pagination, delete confirmation, persistence failure, and successful deletion.
The images were visually inspected. Pager uses the EncoderCompact profile to
select 24 px rows; the compact hybrid/touch layout uses 32 px rows. This does not
infer input capabilities from resolution.

Verification commands:

```text
cmake --build .codex-build/agenda-core
ctest --test-dir .codex-build/agenda-core --output-on-failure
cmake --build .codex-build/agenda-ui
ctest --test-dir .codex-build/agenda-ui --output-on-failure
```

The core build now runs 34 tests, including 24 existing UX/manifest/binding
regressions. The separate LVGL test passes both framebuffer profiles. Remaining
UI work includes creation/editing, date/time/reminder/repeat pickers, reminder
popup, location integration, and complete translation-pack entries. No firmware
or hardware validation has been performed for this checkpoint.

## Editor and picker checkpoint

The page now supports creation and editing through the injected presentation
source/action contracts, plus date, time, reminder and repeat pickers. Title
and note input is checked against the serialized UTF-8 byte limits without
silent truncation. Back can open a discard confirmation without rebuilding
the live text fields; Keep editing preserves even invalid oversized input.
Pending saves disable the actual textareas, and failed saves preserve the
draft and restore editing. Equal start/end clock times mean a 24-hour event;
an earlier end time falls on the next day.

Calendar selection uses the receiving Calendar object for bubbled events,
not the originating buttonmatrix. Passing that matrix to Calendar APIs was
reproduced as a host segmentation fault before the fix. Keyboard/encoder
focus belongs to the editable matrix rather than its container. Directional
keys remain with the widget in edit mode; Tab and Back retain navigation
semantics. Tests cover the matrix's actual bubbling selection event and
directional-key event, in addition to presentation commands.

The LVGL regression renders both real framebuffer geometries and covers CRUD,
picker transitions, duration preservation across date changes, UTF-8 overflow,
discard/keep editing, pending-save input state and write-failure recovery.
Calendar and time controls use the existing shared palette through local
styles; no global theme or LVGL library changes are required. The updated
time and date framebuffer images were visually inspected.

Host touch text-editor attachment is currently stubbed: these tests do not
prove the production touch keyboard or device encoder driver. Translation
pack/font fallback and board power are also stubbed. Location selection is
not yet enabled. Target startup/AppCatalog wiring, the page-independent
reminder popup, full localization, Map integration, firmware builds and device
validation remain outstanding.

## Target composition and catalog checkpoint

At this checkpoint, `esp32_lvgl_arduino_agenda` owned the now-superseded
internal-flash adapter, clock, service,
scheduler, presentation model, injected page Host and ordinary CallbackAppScreen
descriptor. Startup initializes it before building the catalog. The app loop
pumps it after the common loop shell, including that shell's overlay branch;
durable commands therefore do not depend on the Calendar page being alive.
AppContext and AppServicesBundle remain unchanged. A temporary
PresentationWorkspace binds the contracts without adding another permanent
workspace graph.

The descriptor is injected through `FeatureFlags::calendar_app`; callers that
leave it null retain their previous catalog. The production catalog test enables
all optional Pager entries: 15 existing apps plus Calendar equals the unchanged
capacity of 16, with Settings and Shutdown still present and no duplicate IDs.
`targetHasAgenda` checks the LVGL/display capability and the target's Calendar
manifest entry, not resolution. Unsupported Arduino targets compile an inert
adapter without linking Agenda storage, clock or UI dependencies.

Pager and T-Deck now resolve their actual TargetProfile and TargetUxBinding
instead of falling through to the generic `esp_idf` runtime config. Native tests
compile each of WIO, Pager and T-Deck configurations separately and verify the
selected pack exposes Calendar. The root integration test links the real
`agenda.c` asset, page and file-store implementation, substitutes only the clock
and mounted directory, saves while the page is closed and reopens the file to
verify persistence. It does not simulate flash power loss.

At this checkpoint reminder delivery remains disabled in the target adapter
until the global popup can safely own and restore input. This is intentionally
an incomplete runtime: successful compilation is not proof of the required
page-closed reminder scenario. Map/location, translation packs, production touch
keyboard testing and device acceptance are also still outstanding.

### Storage scratch and linked RAM verification

The file adapter no longer retains a second EventRecord. Both banks decode
into the caller's output; if bank 0 wins after reading bank 1, the adapter
rereads bank 0 and verifies its generation. That adds at most one 256-byte read
per logical slot and removes 208 bytes of permanent record storage (216 bytes
including target-root alignment). Initialization uses one bounded automatic
empty record. Slot layout, generation ordering, CRC, durable flush and alternate
bank writes are unchanged. Recovery tests also explicitly cover each bank
surviving corruption of the other.

WIO PlatformIO build completed successfully after this change, exit code 0.
The final ELF reports:

| Symbol / allocation | Bytes | Section |
| --- | ---: | --- |
| Agenda target root, including file adapter, composition, clock, Host and descriptor | 800 | `.dram0.bss` |
| Closed-page state pointer | 4 | `.dram0.bss` |
| Two manifest-backed UX pack objects | 48 | `.dram0.data` |
| Their two local-static initialization guards | 16 | `.dram0.bss` |
| Supplied Agenda bitmap | 12288 | `.flash.rodata` |

The charged idle object subtotal is 868 bytes. A compile-time root assertion
includes the page pointer, both new pack objects and their guards. Making the
pack constructor constexpr did not remove those objects from target RAM; the
subtotal includes them rather than claiming they reside in flash. This is an
object/section measurement, not a runtime heap watermark; shared filesystem
mount overhead and transient LVGL allocations still require device measurement.

Whole-firmware build output: static RAM 98,564 / 327,680 bytes; flash
4,107,425 / 6,291,456 bytes. These are current absolute totals, not a delta
against main. No firmware was uploaded. The native suites pass 38 core,
storage, registration and configuration cases plus 2 LVGL/catalog executables.

## Page-independent reminder presentation checkpoint

The target root now enables reminder delivery through a small injected popup
Host. The popup uses presentation source/action/reminder contracts; it neither
owns the scheduler nor accesses storage. Calendar may be closed throughout
delivery, Snooze and Done. A popup retains one event only while visible and
has a compile-time state limit below 512 bytes; its idle state is one pointer.

Presentation waits for existing overlays, interruption apps, pending shell
transitions and unobserved Calendar commands. Button events enqueue actions;
the following root tick submits the command and observes its result before
closing. Input groups and editing mode are restored only while the popup still
owns input and the previous group still exists. A higher-priority interruption
closes the visual without consuming its reminder or clearing the interruption's
overlay marker. Activation is ignored for the first 400 ms to reject a release
already in flight when the modal opened.

The native tests exercise the real composition, scheduler, presentation model
and LVGL popup at 480x222 and 320x240. Covered scenarios include simultaneous
reminders, monotonic 600-second snooze, refusal of a second concurrent snooze,
Done, interruption/reappearance, a destroyed previous focus group, a record
deleted after a click, and a save result consumed by the page before the due
popup may appear. The target-root integration also exercises persistence and
the complete page-closed reminder path. Shell activity flags, hardware power,
touch keyboard attachment and the clock are host substitutes; these tests do
not prove physical input drivers or the entire production shell lifecycle.

The compact three-action footer allows a two-line caption and uses the taller
320x240 viewport rather than reducing font size. Tests assert caption bounds
and separation between the snooze-capacity error and action buttons. Actual
framebuffers, including this error state, were visually inspected.

The Navigate callback is tested after successful dismissal and popup cleanup,
but the target's Map callback is not wired yet. Location editor selection,
production Map integration, translation pack coverage, production touch input
and device validation remain incomplete. No disabled Navigate button appears
on a location-free event.

The WIO build with the popup linked completed successfully (exit 0, 143.29 s).
Whole-firmware static RAM is 98,564 / 327,680 bytes and flash is
4,111,089 / 6,291,456 bytes. The linked root remains 800 bytes; page and popup
idle pointers are 4 bytes each. Including both 24-byte manifest pack objects
and their two 8-byte guards gives an Agenda-charged object subtotal of 872
bytes. Section alignment means the added pointer did not change the reported
whole-firmware RAM total; the subtotal still charges it explicitly. This does
not measure runtime filesystem heap or peak LVGL allocation. No upload was
performed. The native suites pass 38 core/regression cases and both UI/catalog
executables after the layout and command-handoff tests.

## Location source and Map selection model checkpoint

The Agenda page Host now receives an IAgendaLocationSource. The target owns a
small GpsAgendaLocationSource adapter over the existing IGpsStatusSource;
there is no page-to-hardware call, extra GPS timer or retained GPS snapshot.
Current position requires a valid presentation header, enabled/powered receiver,
valid fix and finite coordinates within geographic bounds. Conversion to E7
occurs only after validation. A failed read leaves the output and editor's
existing location unchanged.

The editor's Location field now opens an optional-location picker. Current
position sets a coordinate in the draft and clears any previous waypoint ID.
Its persisted label is a numeric coordinate rather than a translated phrase.
Remove location clears only location fields/flags. Both actions preserve the
other editor fields and require Save before changing the stored event. Native
UI tests at both geometries cover failure, replacement, Back, removal, save
and subsequent edit; the rendered picker framebuffers were inspected.

MapWorkspaceModel now exposes beginLocationSelection, pickLocation and
cancelLocationSelection with the generic SelectLocation tool. The result is
a bounded structure no larger than 24 bytes. Selection uses the presentation
viewport centre, not the self-position overlay; it accepts (0, 0), rejects
non-finite/out-of-range coordinates, prevents unrelated tool changes while
selecting and restores the previous tool after a successful Pick/Cancel.
Rejected sink operations no longer commit local viewport/tool state. Tests
cover rejection and retry, busy selection, invalid snapshots/coordinates,
zero coordinates, and the pre-existing Map model behaviour.

This is not yet the complete Map-selection workflow. The Map renderer's
Pick/Cancel controls, coordinate-system conversion, shell route handoff,
editor-tree destruction/draft-only retention and reconstruction still require
implementation and integration tests. No Calendar-specific renderer or tile
access has been introduced. Navigation remains unwired. Repository inspection
has not identified an independent saved-waypoint catalog; protocol waypoint
messages are not silently repurposed as such a catalog. The saved-waypoint
source remains unresolved. All 42 core/presentation/registration tests and
both LVGL/catalog test executables pass at this checkpoint.

The added runtime Map adapter regression links the real RuntimeMapWorkspaceSource,
RuntimeMapActionSink and MapWorkspaceModel. It verifies that a committed (0, 0)
viewport is not replaced by a subsequent GPS fix, that the sink sees the
selection tool and its restoration, and that layers remain unchanged.

The WIO location build completed with exit code 0 in 136.80 s: static RAM
98,596 / 327,680 bytes, flash 4,112,353 / 6,291,456 bytes. The root is now
808 bytes, closed page/popup pointers total 8 bytes, and the manifest objects
and guards remain 64 bytes. The existing Map model is 64 bytes, up by 24 from
its former 40-byte layout. Charging that growth yields 904 bytes of Agenda
idle object storage. The root assertion additionally reserves an alignment
unit beyond the selection result, conservatively charging 32 bytes for this
shared-model extension. No hardware upload or live GPS-fix validation was
performed; the reported RAM figures remain linked objects, not heap watermarks.

## Map selection lifecycle checkpoint

Agenda's target-owned UI Flow now connects Choose on map to the existing GPS
shell's Map projection. RouteSpec carries a caller-owned MapLocationRequest;
neither the Map contract nor the renderer depends on Agenda. Flow retains only
an editor draft and bounded return context during the visit. It destroys the
Agenda State, LVGL tree and input group before entering Map, then destroys Map
before reconstructing the editor. Pick updates the draft; Cancel preserves it.
Neither operation writes an event. Closing the app during a pending transition
or an active Map visit releases the return context. Entry failure restores the
draft with an error. Page transitions run outside widget callbacks.

The existing Map runtime provides a fixed viewport-centre crosshair, Pick and
Cancel in selection mode. Route/track controls are not exposed in that mode.
The rendered centre is converted back to WGS84 before E7 storage. Existing
forward coordinate formulas are shared with a bounded inverse; tests pin an
existing forward result, check round trips across all three coordinate modes,
and reject invalid/non-converging input. An explicit initial (0, 0) viewport
receives a valid default zoom instead of being mistaken for an absent centre.

Native lifecycle tests run the real Agenda page and Flow at 480x222 and
320x240, substituting only the Map shell. They assert editor destruction before
Map entry, draft and return-view preservation, Pick/Cancel, unavailable/failed
entry, input-group restoration, zero implicit writes and app exit in both
transition phases. A target-root test also verifies that a reminder due during
selection is presented after returning, without stealing Map input. These
tests do not validate the physical Map renderer, tile service or input drivers.
The updated location-picker framebuffers were inspected at both exact sizes.

All 43 core/presentation/regression cases and both LVGL/catalog executables
pass. The WIO Map-flow build completed with exit 0 in 131.07 seconds. Static
RAM is 98,636 / 327,680 bytes and flash is 4,118,613 / 6,291,456 bytes. Linked
Root storage is 832 bytes. Charging page/popup pointers (8), manifest objects
and guards (64), shared Map-model growth (24), and the three Map selection
pointers (12) gives 940 bytes of idle Agenda-related object storage. The
compile-time guard conservatively charges another alignment unit. These are
object sizes, not heap watermarks. No firmware upload was performed.

Navigation, a resolved saved-waypoint source, translation-pack coverage,
production input validation and the remaining target/device checks are still
incomplete; this checkpoint is not a Calendar V1 completion claim.

## Locale source coverage and detail-return correction

The 13 existing locale tables now contain 62 additional keys for Agenda,
Calendar's catalog label and the Map Pick action. Existing translation quality
statuses are unchanged: this change does not promote review locales. Seven
affected bundle versions receive a minor increment independently of firmware;
the minimum firmware compatibility bounds remain unchanged. Distribution
archives/catalogs have not been published, and the new translations still
require the normal language-quality and on-device layout review.

UI charset/range metadata was regenerated with the existing generator for the
eight affected primary fonts, including the T-Deck Pro Simplified Chinese
variant. Existing non-ASCII charset glyphs were checked against HEAD: none
were removed. Latin, Cyrillic and Arabic build recipes now seed their existing
charsets so future pack builds incorporate added translations while retaining
their previous glyph coverage. Binary font generation and actual glyph lookup
remain separate verification steps; declared ranges alone are not proof of
rendering. Firmware-private dictionaries or embedded CJK font assets were not
added.

The native UI CTest suite includes a Python source-coverage test using the
existing locale parser/validator. It checks Agenda's source keys in every
locale and advertised UI font ranges for the translated characters. All
three UI/catalog/locale tests and all 43 core/regression tests pass.

A new regression reproduced a Map-return bug: detail timestamps were read
from a list row index which no longer referred to the selected occurrence
after page reconstruction. Detail now owns one bounded Occurrence value;
the temporary Map return context preserves it with the editor draft. The test
opens a non-first weekly occurrence, edits without saving, cancels Map, then
discards the edit. It verifies both the original title and the selected
occurrence's start/end display at both screen geometries. The regression was
observed failing before the fix and passing after it. No event is written.
This adds only open-page/temporary-context state, not an idle event table.
The latest WIO binary predates this small detail-state correction; no new
firmware build, upload, commit or push was performed for this checkpoint.

## Detail metadata checkpoint

Event Detail now displays configured reminder and recurrence values. The
editor and detail share the same preset-key functions; no second preset table
or retained presentation state was added. Absent reminder/repeat fields are
omitted. A regression renders all optional fields with a long note at both
480x222 and 320x240, checks that the note remains above the fixed action row,
and verifies that unconfigured metadata is absent. Both exact-size
framebuffers were inspected and the three UI/catalog/locale tests pass.

Map navigation integration inspection found viewport positioning and existing
SelectedTarget overlays, but no generic destination-opening request in the
current shared Map contracts. The pending integration should extend that
shared boundary, not add Agenda-owned map state or imply that turn-by-turn
route planning already exists. Navigate remains unwired at this checkpoint.

## Detail-to-Map target checkpoint

The shared Map route now accepts a caller-owned `MapTargetRequest`, separate
from location selection. It focuses the existing workspace on a validated
WGS84 destination and adds an existing SelectedTarget annotation after optional
information filtering. A full annotation snapshot replaces the last non-self
item rather than dropping the destination or growing the fixed array. Normal
Map routes have no target request. Destination entry does not automatically
load a configured route which would recenter the viewport. This is destination
display, not turn-by-turn routing or route calculation.

Event Detail now exposes Navigate only for located events with an available
host action. The existing Flow coordinator defers teardown until outside the
UI callback, destroys the Agenda tree, opens Map, and reconstructs Detail on
Back. It preserves the selected occurrence and does not write the event.
Selection continues to reconstruct the editor instead. Entry failure returns
to the original view with an error. The return context remains below 1 KiB;
only one additional shared Map pointer is retained while idle.

Native tests cover zero/boundary/invalid coordinates, action-sink rejection,
selection conflicts, annotation capacity, both Detail return geometries,
entry failure, and no unintended event writes. The all-fields framebuffer
checks now include Navigate at 320x240 and 480x222. All 44 core/regression
tests and three UI/catalog/locale tests pass. The native Map-flow test still
substitutes the Map shell; it does not prove physical input or tile rendering.

Expanded UI testing exposed a pre-existing Agenda input bug: LV_EVENT_KEY
holds a key-value pointer, but the handler passed it to lv_indev_stop_processing
as an input-device pointer. A debugger data watchpoint observed corruption of
an adjacent host field. Page key handling now uses the active input device;
the popup distinguishes key events from pointer/click events. Both paths have
guarded key-payload regressions. These are firmware fixes, not test-only changes.

Reminder-popup navigation across application lifetimes remains unwired.
Saved-waypoint source integration and full device validation also remain open.

WIO `wio_tracker_l2` was rebuilt after the input fix: PlatformIO exited 0
after 132.33 seconds, static RAM 98,644/327,680 B and flash
4,120,177/6,291,456 B. The idle RAM static assertion remains satisfied.
No upload, commit, push or release was performed. Other target builds and
hardware behavior are not established by this WIO build.

## Reminder navigation and approved-target build checkpoint

Reminder Navigate now prepares a bounded return context before submitting
dismissal. Preparation or command failure leaves the reminder available and
cancels the prepared navigation. Successful dismissal closes the popup before
the target composition uses the existing application switch and Map route.
An already-open Agenda restores its view and draft; invocation from another
application returns to the default Agenda list. Picker values remain provisional.

All four approved targets built successfully in the same PlatformIO run (exit
0). These results precede the content-font and interruption changes below.

| Environment | Static RAM (B) | Flash (B) |
| --- | ---: | ---: |
| wio_tracker_l2 | 98,644 | 4,121,253 |
| tdeck | 96,040 | 4,043,773 |
| tlora_pager_sx1262 | 99,696 | 4,240,365 |
| tlora_pager_lr1121 | 100,112 | 4,242,033 |

## Font artifact and scope verification

Generated binaries for all eight affected primary fonts pass real LVGL glyph
lookup for the Agenda translations. Actual generation exposed missing Polish
letters, Arabic-pack punctuation and a mathematical comparison symbol. Latin
now uses Noto Sans with CJK fallback for missing symbols; Arabic retains Naskh
with Noto Sans fallback. The converter assigns each character to the first
source containing it, so fallback does not replace primary glyphs. Source and
pack licenses accompany the new font source. Distribution archives remain
unpublished; language quality and Arabic shaping are not proven by glyph lookup.
Full-charset lookup also passes for the other seven fonts. Arabic's existing
broad charset declaration fails at U+0605, despite Agenda's required characters
passing; full Arabic advertised-range coverage is not established.

User-entered Agenda labels now use the existing Content font scope, while
translated controls use the Ui scope. A native regression failed on the old
helper and passes on both layout profiles, for body and caption fonts.

The optional GNU font artifact test instruments the real LVGL loader, reports
retained allocation payload and load-time peak, and checks release on destroy.
The 32-bit retained payload measurements are:

| Font | Retained payload (B) | Manifest estimate (B) |
| --- | ---: | ---: |
| ar-naskh | 50,939 | 52,224 |
| cyrillic-eu | 3,900 | 5,120 |
| latin-ext-eu | 2,582 | 4,096 |
| ja-cjk | 33,331 | 34,816 |
| ko-cjk | 24,770 | 26,624 |
| tdeckpro-zh-hans-core | 137,092 | 139,264 |
| zh-hans-core | 222,663 | 224,256 |
| zh-hant-cjk | 37,675 | 38,912 |

`verify_font_artifacts.py` checks glyphs and requires a manifest estimate at
least the retained payload rounded up to 1 KiB plus a further 1 KiB allowance.
These are estimates, not physical-device heap watermarks or load-peak budgets;
allocator metadata, libc I/O and rendering allocations are not measured.
Ordinary CTest neither downloads dependencies nor regenerates fonts.

## Interrupted-page recovery checkpoint

The existing app runtime sets the interruption flag before calling the previous
application's exit callback. Agenda Flow now distinguishes that exit from a
normal close. It releases Agenda/Map widgets and input groups while retaining
one bounded recovery context. The shell must re-enter Calendar to resume it;
a suspended context cannot independently activate the application.
If an interruption superseded an exit-to-menu and the shell does not resume
Calendar, target composition discards the suspended context once the shell is
stable. Reopening Calendar then starts a new session. A root-level regression
reproduced stale-session resurrection before this cleanup was added.

Recovery includes the draft, selected occurrence, list query, provisional
date/time values, delete/discard confirmation and pending command sequence.
Live text has a separate bounded UTF-8 representation because LVGL's character
limit can exceed the persistent record's byte limit. Invalid oversized text is
restored for correction, never silently truncated or written. The context is
reserved before accepting input and reused for Map returns; it remains below
1 KiB. Normal close releases the reserve. Idle ownership grows by one pointer,
not by a persistent draft buffer.

Native regression first reproduced lost editor state after actual Flow exit
and enter callbacks. Both geometries now pass normal and maximum-size live text,
confirmation, picker, prepared-navigation cancellation, interrupted Map return,
and save success/failure during interruption. The test substitutes the external
interruption application and Map shell: it does not prove the production call
screen, keyboard integration or physical input. The latest native suites pass
44 core/regression and four UI/catalog/localization tests.

Saved-waypoint integration, full production input/Map/device validation,
physical memory measurements and the complete specification audit remain open.

Production touch-editor inspection identifies an additional recovery boundary:
the compact touch keyboard edits its own modal textarea until OK, whereas
Agenda's recovery snapshot currently reads the source field. Deleting the source
closes that modal without applying its unconfirmed text. A combined production
touch-editor/Agenda test and a shared editor recovery contract are still needed;
the page-field interruption tests do not cover this separate modal draft.

WIO was rebuilt with the completed page-field recovery and abandoned-session
cleanup: PlatformIO exit 0, 122.63 seconds, static RAM 98,652/327,680 B and flash
4,122,157/6,291,456 B. The idle and recovery-context assertions pass on ESP.
ESP stack hygiene and `git diff --check` pass. No firmware upload was performed;
the latest Pager and T-Deck builds still predate these recovery changes.

## Production touch-input integration checkpoint

The Agenda native UI target now compiles the real compact touch editor,
ImeWidget, PinyinIme and input-layout adapter instead of replacing
`attach_touch_text_editor` with a no-op. Board keyboard-device lookup and the
external language-pack source remain host fixtures; the fixture does not enable
a Pinyin dictionary and does not establish language-specific composition recovery.

At 320x240, the production DeckLandscape/Touch layout enables the compact
keyboard. A combined test opens Agenda's title and note editors, sends actual
buttonmatrix key events, checks keyboard bounds, verifies Cancel leaves the
source unchanged, verifies OK writes the field but not the store, and verifies
Save persists both fields without requiring a location. The four UI/catalog/
localization tests pass with this stronger input boundary.

Unconfirmed modal text across application interruption is still not restored.
The shared editor retains a separate draft and Cancel semantics; copying it into
the source on interruption would be an incorrect implicit commit. Recovery must
preserve that distinction and account for IME state and bounded temporary RAM.
This checkpoint changes tests only; it does not add a new firmware build result.

## Shared modal recovery implementation checkpoint

The compact touch editor now exposes capture/restore operations using caller-
provided text storage and a bounded `ImeEditState`. It retains no additional
global draft or widget tree. The IME metadata preserves mode, shift, cursor,
script selection, the eight-letter composition buffer and candidate state;
candidate collections are reconstructed rather than retained.

Agenda Flow captures the modal independently of its source field and restores
it after rebuilding the source. A regression first failed with missing modal
text, then passed after integration. Combined tests cover Cancel/OK semantics,
numeric/symbol layout, shift and cursor restoration, a deterministic two-entry
Pinyin fixture, and maximum-length four-byte UTF-8 source and modal strings.
All four native UI/catalog/localization tests pass. Physical touchscreen and
full language-pack dictionary behavior remain outside this evidence.

The initial integrated return context allocates 1,272 B on the 32-bit native
build (allocation immediate 0x4f8 in Flow::enter), exceeding the previous 1 KiB
recovery ceiling. A temporary 1.5 KiB ceiling keeps growth bounded; this is not
a completed RAM-budget acceptance. Compacting duplicated draft text and
mutually exclusive Map/modal state remains required before final validation.
No new firmware build or upload was performed for this checkpoint.

## Compact recovery text checkpoint

Agenda now stores transient source and modal drafts as bounded 21-bit Unicode
scalar snapshots. The persistent event format and input character limits are
unchanged. Invalid UTF-8 or excess characters reject capture without truncation;
restoration streams individual scalars into LVGL without a full decoded scratch
buffer. Shared touch-editor callbacks keep the encoding out of the shared IME.

The 32-bit native recovery allocation is now 1,008 B (0x3f0), down from 1,272 B.
The compile-time ceiling is restored to strictly below 1 KiB. This is a native
context measurement, not an ESP heap-watermark or firmware static-RAM result.

Five native UI/catalog/localization/snapshot tests pass, including the existing
maximum-length independent source/modal interruption cases. The snapshot test
round-trips every non-NUL Unicode scalar and checks invalid encodings, capacity
rejection, unchanged state on rejection, and early consumer termination. The
standalone shared touch-editor test and ESP stack-hygiene check also pass.
Firmware rebuild and hardware validation remain outstanding for these changes.

The subsequent WIO PlatformIO build completed with exit 0 in 124.02 seconds.
It includes shared modal recovery and compact text snapshots; the ESP recovery
context size assertion passes. Static RAM is 98,652/327,680 B, unchanged from
the previous WIO checkpoint; flash is 4,124,481/6,291,456 B. No upload was done.
The 44-test core/regression suite was rerun and passed. Pager/T-Deck rebuilds,
hardware validation and saved-waypoint product integration remain outstanding.

## Native framebuffer review checkpoint

The core build was refreshed before rerunning all 44 passing tests, including
the rebuilt disabled-target executable. Actual native LVGL framebuffer outputs
were visually inspected at their original sizes: the 320x240 editor, date and
time pickers, and snooze-conflict reminder; the 480x222 Agenda, full-field detail
and located reminder. These English fixtures show no text/button overlap. The
compact editor scrolls its fields while Save remains outside the scroll area.
This limited review does not prove all translations, physical input behaviour,
production font-pack layout, or complete device acceptance.

## T-Deck recovery build checkpoint

The latest T-Deck firmware, including shared IME/modal recovery and compact
Agenda snapshots, builds successfully: PlatformIO exit 0, 107.16 seconds,
static RAM 96,048/327,680 B and flash 4,047,005/6,291,456 B. This validates the
compiled target path, not physical keyboard/trackball behaviour. No upload was
performed. The eight existing font binaries were rechecked for Agenda-required
glyph mappings and declared RAM estimates; all passed. Pager builds and the
remaining product/device acceptance items are still open.

## Pager recovery build checkpoint

Both Pager environments now build the latest recovery implementation successfully
(combined PlatformIO exit 0). SX1262: 113.42 seconds, static RAM 99,704/327,680 B,
flash 4,243,529/6,291,456 B. LR1121: 128.26 seconds, static RAM 100,120/327,680 B,
flash 4,245,185/6,291,456 B. Along with the preceding WIO and T-Deck builds,
all four approved firmware environments compile the compact recovery path.
No uploads were performed. These builds do not establish physical input,
power-loss behaviour or runtime heap-watermark acceptance; saved-waypoint
integration also remains incomplete.

## Editor field focus recovery correction

An interruption regression exposed that focusing Date without activating it
left the draft's remembered field unchanged. Textareas remembered focus, but
the five picker field buttons did not. Those buttons now use the same existing
focus callback; no additional state or shared focus-manager branch is needed.
The regression first failed, then passed for Date, Time, Reminder, Location
and Repeat across both native profiles. All five UI test targets pass. This
small correction postdates the four firmware build checkpoints above and has
not yet been rebuilt for ESP or tested with physical input.

## Local waypoint integration checkpoint

Local named waypoints use a separate portable `core_waypoint` module. This
checkpoint used an internal-flash file adapter, which must be replaced by an
SD runtime adapter under the current contract. The 64-slot store scans records on demand; the
picker retrieves at most five rows. Its presentation model retains one pending
write, not a database cache. The composition root creates the bounded waypoint
session when Calendar opens and releases it after ordinary exit. Interrupted
Calendar sessions preserve pending results until the UI can consume them.

Selecting a waypoint copies its name, coordinates and identifier into the event
draft without saving the event. Naming and saving a location creates a waypoint
independently of event persistence. Compact touch-editor tests cover independent
source/modal text across interruption, Cancel without writeback, OK without
persistence, and explicit asynchronous Save followed by return to the editor.
Six waypoint tests and five UI tests pass. The 44-test core/registration suite
and ESP stack-hygiene check also pass.

All four approved PlatformIO environments now build the waypoint integration
and editor focus recovery correction successfully (exit code 0):

| Environment | Static RAM (bytes) | Flash (bytes) |
| --- | ---: | ---: |
| wio_tracker_l2 | 98,660 | 4,131,069 |
| tdeck | 96,056 | 4,053,221 |
| tlora_pager_sx1262 | 99,712 | 4,249,917 |
| tlora_pager_lr1121 | 100,128 | 4,251,561 |

These are link-time measurements, not runtime heap measurements. No firmware
was uploaded. Physical input, on-device persistence/power-loss behavior,
runtime heap watermarks, and final waypoint UI wording/layout remain unverified.

## Waypoint UI and recovery validation

Native LVGL fixtures now render the waypoint list, name editor and failed-save
state at both 320x240 and 480x222. The English outputs were inspected without
scaling; rows, buttons and error status remain inside the framebuffer. Tests
cover five-row pagination, return navigation and retention of an unsaved name
after an asynchronous write failure. This is not multilingual layout or physical
input acceptance.

The expanded lifecycle fixture exposed an aliasing bug in IME restoration:
`restoreEditState` accepted the textarea's internal text pointer, then changed
mode before copying it. Mode changes can replace that buffer. Restoration now
takes ownership through the existing `setText` path before changing mode. No
additional recovery buffer was added. The five Agenda UI tests and standalone
shared touch-editor test pass after this correction.

Waypoint validation now checks bounded UTF-8 as well as record identity and
coordinate ranges. Tests reject overlong, surrogate, out-of-range and truncated
sequences, including the fixed-field boundary, while accepting valid multibyte
names. All six waypoint tests pass. The on-disk format is unchanged.

Font cases were regenerated from current Agenda sources and all 13 locale files,
including the waypoint labels. All eight existing binary font artifacts contain
the required mapped glyphs and satisfy their declared retained-RAM estimates in
the 32-bit native loader probe. This does not establish shaping quality, visual
translation quality, or device heap watermarks. The firmware build table above
predates these latest validation and IME changes.