OSIT-AE-App-Svelte/documentation/PROJECT__Stores_Svelte5_Migration.md

# Project: Svelte 4 Store → Svelte 5 State Migration

**Status:** Events module — COMPLETE. Core / IDAA — In Progress (field cleanup done, PersistedState pending).
**Priority:** High
**Created:** 2026-03-30
**Last Updated:** 2026-06-11

---

## Background

All core Aether stores were built with `svelte-persisted-store` (Svelte 4 contract). This provides
coarse reactivity: any write to any field notifies *all* subscribers and re-serializes the entire
object. For large stores like `ae_loc` and `ae_events_loc`, this caused unnecessary re-renders and
was the root cause of the IDAA "Access Denied" corruption bug (a bootstrap write to `ae_loc` would
overwrite `authenticated_access` if a persisted value was slightly different, corrupting IDAA
member state stored in the same key).

The migration target: replace all `persisted()` stores with `runed`'s `PersistedState`, which uses
Svelte 5 fine-grained reactivity — a write to one field only triggers effects that read that field.

---

## Completed: Events Module (2026-06-11)

All `ae_events_stores` sub-modules have been promoted to their own `PersistedState` stores and
`events_loc` (the old `persisted()` store) has been **fully retired**.

| Store | File | localStorage key | Status |
|---|---|---|---|
| `badges_loc` | `ae_events_stores__badges.svelte.ts` | `ae_badges_loc` | ✅ Done (2026-04-02) |
| `leads_loc` | `ae_events_stores__leads.svelte.ts` | `ae_leads_loc` | ✅ Done (2026-04-03) |
| `pres_mgmt_loc` | `ae_events_stores__pres_mgmt.svelte.ts` | `ae_pres_mgmt_loc` | ✅ Done (2026-04-03) |
| `launcher_loc` | `ae_events_stores__launcher.svelte.ts` | `ae_launcher_loc` | ✅ Done (2026-06-11) |
| `events_auth_loc` | `ae_events_stores__auth.svelte.ts` | `ae_events_auth_loc` | ✅ Done (2026-06-11) |
| `events_loc` | *(retired)* | `ae_events_loc` | ✅ Store removed (2026-06-11) |

`ae_events_stores.ts` now only exports `events_sess` (in-memory writable, no migration needed),
`events_slct`, `events_trig`, `events_trig_kv`, `events_trigger`, and the `EVENTS_MODULE_TITLE`
constant. The file no longer imports `svelte-persisted-store`.

`store_versions.ts` still calls `_check_and_wipe('ae_events_loc', AE_EVENTS_LOC_VERSION)` to clean
old data out of users' browsers — this is intentional and should be kept for at least one year.

---

## In Progress / Remaining: `ae_stores.ts` and `ae_idaa_stores.ts`

Both stores had their unused default properties pruned (2026-06-11), reducing migration scope:

**`ae_loc`** (in `ae_stores.ts`) — still `persisted('ae_loc', ...)`:
- Remaining fields: auth/identity, theme, permissions, ui config, file upload tracking, query prefs
- This is the highest-impact remaining migration — used in nearly every route
- Root cause of IDAA "Access Denied" bug (coarse write during bootstrap stomps on permission fields)

**`idaa_loc`** (in `ae_idaa_stores.ts`) — still `persisted('ae_idaa_loc', ...)`:
- Remaining fields: `novi_uuid/verified/ts`, `novi_admin_li/trusted_li`, `archives/bb/recovery_meetings` sub-objects
- Fields pruned (2026-06-11): `ds`, `idaa_cfg_json`, top-level `qry__*`, `novi_*_base_url`, `novi_rate_limited_until`

---

## Migration Pattern (Established)

Each sub-store follows this pattern, using the `badges` store as the canonical reference:

### 1. Defaults file (`*_defaults.ts`)
Define the shape and defaults as a plain TypeScript object (and interface if complex):

```ts
export interface BadgesLocState { ... }
export const badges_loc_defaults: BadgesLocState = { ... };
```

### 2. Store file (`*.svelte.ts`)

**Updated 2026-06-16 — stamp `__version` in the serializer.** The original pattern below (bare
`JSON.stringify`) looked fine but has a real failure mode: `store_versions.ts`'s
`_check_and_wipe()` compares a `__version` field *inside* the stored JSON, and a bare
`JSON.stringify` never writes one. Two consequences were found in production code:
`pres_mgmt_loc`'s version bump was silently a no-op (never wired into `_check_and_wipe` at
all), and `leads_loc`'s *was* wired in, so `parsed?.__version` was always `undefined` —
always failing the comparison — wiping `ae_leads_loc` on **every single page load**. Both
fixed 2026-06-16. `badges_loc`, `launcher_loc`, and `events_auth_loc` still use the old bare
pattern below and are **not yet wired into `_check_and_wipe`** — not actively harmful (the
wipe never runs), but apply this fix before wiring any of them in.

```ts
import { PersistedState } from 'runed';
import { badges_loc_defaults } from './ae_events_stores__badges_defaults';
import { AE_BADGES_LOC_VERSION } from './store_versions';

export const badges_loc = new PersistedState('ae_badges_loc', badges_loc_defaults, {
    serializer: {
        // Stamp __version on every write so store_versions.ts's _check_and_wipe() can
        // detect a breaking schema change and clear stale browsers on next load. This
        // import also guarantees store_versions.ts's wipe side-effect runs before this
        // PersistedState reads from localStorage (ES module execution order).
        serialize: (value) =>
            JSON.stringify({ ...value, __version: AE_BADGES_LOC_VERSION }),
        // Merge with defaults so new fields added after first session get their defaults,
        // and strip __version back out so it doesn't pollute the typed state object.
        deserialize: (raw: string) => {
            const { __version, ...stored } = JSON.parse(raw);
            return { ...badges_loc_defaults, ...stored };
        }
    }
});
```

Then in `store_versions.ts`'s startup block:
```ts
_check_and_wipe('ae_badges_loc', AE_BADGES_LOC_VERSION);
```

See `ae_events_stores__pres_mgmt.svelte.ts` and `ae_events_stores__leads.svelte.ts` for the
two real, currently-correct examples of this pattern.

### 3. Consumer syntax
```ts
// Import (note .svelte extension, not .svelte.ts):
import { badges_loc } from '$lib/stores/ae_events_stores__badges.svelte';

// Read:
badges_loc.current.fulltext_search_qry_str

// Write (fine-grained — only triggers effects that read this field):
badges_loc.current.fulltext_search_qry_str = 'hello';

// Bulk reset:
badges_loc.current = { ...badges_loc_defaults };
```

### Key differences from old `svelte-persisted-store` pattern:
| | Old (`persisted()`) | New (`PersistedState`) |
|---|---|---|
| Import | `import { events_loc } from '...ae_events_stores'` | `import { badges_loc } from '...ae_events_stores__badges.svelte'` |
| Read | `$events_loc.badges.field` | `badges_loc.current.field` |
| Write | `$events_loc.badges.field = x` | `badges_loc.current.field = x` |
| Reactivity | Coarse — entire store notified | Fine-grained — only affected fields |
| In `$effect` | Subscribes to entire store | Only subscribes to fields you read |

---

## Next Steps

1. **`idaa_loc` → PersistedState** — Highest priority for IDAA stability. Promotes `novi_uuid/verified`,
   `archives`, `bb`, `recovery_meetings` sub-objects to their own stores following the same pattern.
   Primary benefit: eliminates the IDAA "Access Denied" corruption from `ae_loc` bootstrap writes.
   Use the `__version`-stamping serializer from the start (see Migration Pattern above) and wire
   it into `_check_and_wipe()` immediately — `idaa_loc` holds auth state, so a real wipe-on-schema-
   change matters more here than anywhere else this pattern has been applied so far.

2. **`ae_loc` → PersistedState** — Largest scope (~every route in the app). Defer until after
   `idaa_loc` is done. Consider extracting `auth_loc` (the identity/permission fields) as the
   first sub-store since those are the fields implicated in the IDAA corruption bug.