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

# Aether SvelteKit — Common Agent Mistakes (Reference)

This is the detailed mistake catalog referenced by `BOOTSTRAP__AI_Agent_Quickstart.md`.
Use it as a troubleshooting and prevention guide, not as first-pass onboarding.

Review policy: balanced curation.
- Keep: high-impact or recurring mistakes.
- Archive: one-off or lower-signal historical incidents.

---

## Active Mistakes (Curated)

### 1) IDAA content exposed publicly
**Impact:** Sev-1 privacy breach.

**What happened:** A route guard was removed on an IDAA BB route.

**Rule:** All `/idaa/` content is private. Never remove auth guards on IDAA routes.

**Verify:** Confirm route/layout auth checks still gate all IDAA pages before data load.

### 2) Object ID included in PATCH body (`data_kv`)
**Impact:** 400 errors (`Unknown column in SET`).

**What happened:** Object ID (for URL path) was also sent in `data_kv`.

**Rule:** Keep object ID in the URL only; `data_kv` contains changed fields only.

**Verify:** In `update_ae_obj__*` calls, confirm `data_kv` excludes `*_id` fields.

### 3) Coarse-store `$effect` reactivity loops
**Impact:** repeated fetches, duplicate side effects, noisy state churn.

**What happened:** `$effect` read fields from `svelte-persisted-store` stores (`$ae_loc`, `$idaa_loc`), subscribing to entire store.

**Rule:** Be minimal about coarse-store reads in `$effect`; move transient triggers to session state and keep duplicate guards in executor paths.

**Verify:** Check effect dependencies and ensure unrelated writes do not retrigger critical effects.

### 4) Dexie `.get()` used with string object ID
**Impact:** false misses (`undefined`) despite cached data.

**What happened:** `.get()` queried primary key `id`, but V3 records rely on object string IDs (e.g. `person_id`).

**Rule:** Use `.where('<obj_id>').equals(value).first()` for object lookups.

**Verify:** Search for `.get(` against object IDs and replace with indexed `where` query.

### 5) Misunderstanding `$effect` and auth gates
**Impact:** security confusion and wrong mitigations.

**What happened:** Child-component `$effect` blocks were treated as possible bypass vectors.

**Rule:** Child effects cannot bypass parent layout auth gates; pre-gate risk is in universal `+page.ts` / `+layout.ts` loads and prefetch.

**Verify:** Keep private-module data loads out of universal load files unless explicitly authenticated.

### 6) Using query `key` like `x-no-account-id: bypass`
**Impact:** dropped `x-account-id`, unexpected 403 on scoped requests.

**What happened:** `key` was treated as bypass intent and account context was stripped.

**Rule:** `key` is business data, not bypass intent. Only explicit `x-no-account-id: bypass` drops account context.

**Verify:** Check request headers for account-scoped calls and preserve `x-account-id` unless bypass is explicitly required.

### 7) Pre-stringifying `*_json` before API wrappers
**Impact:** double encoding risk and inconsistent payloads.

**What happened:** Callers stringified JSON fields manually before wrapper serialization.

**Rule:** Pass plain objects for `*_json` fields; wrappers handle serialization.

**Verify:** Remove `JSON.stringify(...)` around `cfg_json`, `data_json`, and related fields before wrapper calls.

### 8) Broad Dexie result windows silently clipped
**Impact:** “All” views show fewer rows than narrower filters.

**What happened:** page limits or API revalidation replaced local broad result sets.

**Rule:** For empty text search, local IDB result set should drive visible results; server refresh updates cache without shrinking display.

**Verify:** Compare empty-search “All” view vs narrower filter counts and inspect revalidation merge behavior.

### 9) Missing `IDB_CONTENT_VERSIONS` bump after `properties_to_save` changes
**Impact:** long-lived stale cache bugs (e.g. IDAA “no meetings found”).

**What happened:** shape persisted in IDB changed, but table content version was not bumped.

**Rule:** When persisted object shape/behavior changes, bump matching `IDB_CONTENT_VERSIONS` entry in `src/lib/stores/store_versions.ts`.

**Verify:** For relevant object changes, confirm both version increment and table-wiring path are in the same change set.

### 10) API retry loop broken by returning transient errors
**Impact:** no retries on common WiFi/network blips.

**What happened:** transient error paths returned `false` instead of throwing, bypassing retry loop.

**Rule:** Keep retry classification strict:
- transient `TypeError` and timeout aborts -> `throw`
- navigation abort -> `return false`
- deterministic 4xx -> `return false`
- 5xx -> `throw`

**Verify:** Simulate transient network failure and confirm retry/backoff attempts occur.

### 11) Account-scoped trigger fired before bootstrap account is ready
**Impact:** wrong-account API fetch and cached cross-account data.

**What happened:** trigger effects ran before account bootstrap settled, reading stale context.

**Rule:** Gate account-scoped load triggers on `$slct.account_id` readiness, not persisted `$ae_loc.account_id`.

**Verify:** Ensure trigger effects require browser + account_id + api readiness before fetch trigger assignment.

### 12) `tmp_sort_*` comparator direction inverted
**Impact:** priority ordering reversed.

**What happened:** descending comparator used with `build_tmp_sort` encoding (which expects ascending).

**Rule:** Use ascending compare for `build_tmp_sort` outputs, with documented exceptions for legacy encodings.

**Verify:** Confirm comparator direction per module encoding and avoid `collection.reverse().sortBy(...)` assumptions.

### 13) `$` sigil used on plain prop values
**Impact:** runtime `store_invalid_shape` errors.

**What happened:** child component treated normal prop values as Svelte stores.

**Rule:** In Svelte 5, props passed as values are plain values. Do not use `$prop` unless prop is an actual store.

**Verify:** In migrated components, replace `$lq__...` prop reads with plain `lq__...` prop access.

### 14) Null JSON blob fields not guarded
**Impact:** read/write crashes (`cannot access property of null`).

**What happened:** `*_json` / `*_kv_json` DB columns were null before first write.

**Rule:** Use optional chaining for reads and `?? {}` initialization before object spread writes.

**Verify:** Audit reads/writes for `cfg_json`, `data_json`, `poc_kv_json`, and similar nullable blob fields.

### 15) Service worker stale-tab behavior misunderstood
**Impact:** users run old code longer than expected, “can’t reproduce” bug reports.

**What happened:** deployment assumptions ignored SW activation lifecycle.

**Rule:** Keep SW activation behavior explicit (`skipWaiting`, `clients.claim`) and evaluate trade-offs for session-heavy flows.

**Verify:** After deploy, validate that long-lived tabs pick up new SW behavior as intended.

---

## Archived Historical Items (Pruned)

These are retained as project memory but removed from the active mistake list because they are lower-signal or one-off.

1. **Bad `.d.ts` module declaration masking errors** (important incident, low recurrence recently).
2. **Launcher `file_purpose == 'admin'` filtering gap** (specific historical enum-audit miss).
3. **Deleting files with `rm`** (still a workflow rule, now maintained in bootstrap File Safety section rather than as a mistake entry).

---

## Related Docs

- `documentation/BOOTSTRAP__AI_Agent_Quickstart.md`
- `documentation/TODO__Agents.md`
- `documentation/GUIDE__SvelteKit2_Svelte5_DexieJS.md`
- `documentation/GUIDE__AE_API_V3_for_Frontend.md`
- `documentation/PROJECT__Stores_Svelte5_Migration.md`