# Event Storage and Identifiers

!!! abstract "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.

!!! info "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`