Event Storage and Identifiers

Storage philosophy

Runtime speed and correctness come from a compact in-memory model plus stable cross-provider identifiers. This page documents that storage contract.

EventStore model

EventStore is an in-memory indexed store with one primary key and two operational secondary indexes.

Index	Key	Used for
Primary	Session ID	Direct event retrieval and mutation addressing in runtime/UI.
Secondary	Calendar ID	Fast calendar-scoped reads and resync rendering.
Secondary	File path	Fast file-scoped sync when local files change.

Line-number metadata is tracked for local-file backed events to support precise write/update paths.

Identifier system

Two IDs are intentionally maintained:

1. Session ID: transient runtime ID generated by the registry/cache pipeline.
2. Global identifier: stable provider-facing key in the form calendarId::persistentId.

ProviderRegistry owns the global identifier -> session ID mapping so features like recurring overrides and provider update ingestion can reconcile stable source identity with current runtime entries.

Sync semantics

• Calendar sync replaces/updates store state for a provider with normalized events.
• File sync computes definitive file-scoped state and applies atomic replace behavior for that file slice.
• resync publish mode is used when broad rebuild/reconciliation is required.

Why this matters

Without indexed storage and dual-ID mapping, local file updates and remote refresh reconciliation would require expensive full scans and fragile matching.

Integration anchors

• src/core/EventStore.ts
• src/core/EventCache.ts
• src/providers/ProviderRegistry.ts