# Task 1.6 — Per-device in-memory state

**Phase:** 1 — Throughput pipeline
**Status:** 🟩 Done
**Depends on:** 1.2
**Wiki refs:** `docs/wiki/entities/processor.md` (§ State management)

## Goal

Maintain a bounded `Map<device_id, DeviceState>` updated on every accepted Position. Phase 1 only stores trivial state — `last_position`, `last_seen`, `position_count_session` — but the structure is built so Phase 2 (geofence accumulators, time-since-last-checkpoint, etc.) can extend it cleanly.

## Deliverables

- `src/core/state.ts` exporting:
  - `createDeviceStateStore(config, logger): DeviceStateStore` — factory.
  - `DeviceStateStore` interface:
    - `update(position: Position): DeviceState` — applies the position, returns the new state. Touches LRU order.
    - `get(device_id: string): DeviceState | undefined` — read without touching LRU order. (Used for diagnostics; the hot path uses `update`.)
    - `size(): number` — for metrics.
    - `evictedTotal(): number` — for metrics.
- `test/state.test.ts` covering:
  - First update for a new device creates the entry; subsequent updates increment `position_count_session`.
  - LRU eviction: with cap=3, after 4 distinct devices, the least-recently-updated is evicted.
  - Eviction increments `evictedTotal()`.
  - `last_seen` reflects the position's `timestamp` (the device-reported time), not the wall clock at update time.
  - Out-of-order positions (a position with `timestamp` older than `last_seen`) are still applied (we don't drop them) but `last_seen` only advances forward — i.e. `last_seen = max(prev_last_seen, position.timestamp)`. Document the rationale.

## Specification

### LRU implementation

Use a plain `Map<string, DeviceState>`. JavaScript `Map` preserves insertion order, and we exploit it: on every `update`, `delete` then `set` the entry — that bumps it to the most recent position in iteration order. When `size() > cap`, take `keys().next().value` (the oldest) and `delete` it.

This is O(1) per update and avoids a third-party LRU dependency. **Do not** introduce `lru-cache` — the standard `Map` trick is sufficient for Phase 1's needs.

### Why `last_seen = max(...)`, not `last_seen = position.timestamp`

Devices buffer records when offline and replay them in bursts (we observed a 55-record buffer flush on stage). Within a single batch, timestamps may *decrease* between consecutive records if the device sorted them oddly. We want `last_seen` to mean "highest device timestamp seen so far for this device" — that's what downstream consumers want.

### What about restart?

On Processor restart, the in-memory state is empty. The first record from any device creates a fresh `DeviceState`. **Phase 1 accepts this** — it's a recovery path, not a hot path, and Phase 1 has no domain logic that would be wrong without rehydrated state.

Phase 3 (production hardening) adds rehydration: on first packet for an unknown device, query `positions WHERE device_id = $1 ORDER BY ts DESC LIMIT 1` to seed `last_position`. That's a Phase 3 task, not Phase 1.

### What state lives here, what doesn't

In Phase 1 the state is intentionally minimal:

```ts
type DeviceState = {
  device_id: string;
  last_position: Position;
  last_seen: Date;                // = max(prev, position.timestamp)
  position_count_session: number; // resets on restart
};
```

**Not in Phase 1:**
- Geofence membership (Phase 2)
- Distance accumulators (Phase 2)
- Time-in-stage (Phase 2)
- Anything that would be wrong if dropped on restart (Phase 3 + rehydration)

The interface is built to extend: Phase 2 may add fields, but the existing fields and method signatures should not change.

## Acceptance criteria

- [ ] `pnpm typecheck`, `pnpm lint`, `pnpm test` clean.
- [ ] LRU cap from `DEVICE_STATE_LRU_CAP` config is respected.
- [ ] `evictedTotal()` increments correctly under eviction.
- [ ] `last_seen` does not regress on out-of-order timestamps.

## Risks / open questions

- **Cap sizing.** Default `DEVICE_STATE_LRU_CAP=10000`. At 1KB per state entry, that's 10MB of resident memory — fine. Operators with unusually large fleets can raise it; the bound exists to prevent runaway growth from misbehaving devices flooding novel `device_id` values.
- **No mutex.** State is updated only from the consumer loop, which is single-threaded. If Phase 2 introduces parallel sinks, revisit with proper synchronization.

## Done

`src/core/state.ts` — LRU Map using delete+set bump trick, `last_seen = max(prev, position.timestamp)` semantics, `evictedTotal()` counter. `test/state.test.ts` — 14 tests covering new-device creation, session counter increment, LRU eviction at cap, LRU re-touch, evictedTotal, out-of-order timestamp rejection, get/size. Landed in `68d3da3`.