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.

16) Local "shadow field" silently bypasses the admin-synced master field

Impact: an admin config toggle appears to do nothing — the UI updates fine when a local per-browser preference is clicked, but the actual admin setting has zero effect, at any permission level. Looks like a permissions bug; isn't one.

What happened: A list/table column's visibility prop was computed from only a local-only, never-synced preference field (e.g. hide__session_li_location_field), while a similarly-named, admin-synced field (hide__session_location) existed and was correctly synced — just never read at that particular render call site. Found twice in the same session (Pres Mgmt POC column, then Location column).

Rule: When a remote config field and a local-only preference field could plausibly both affect the same visible thing, combine them explicitly (admin_field || local_field) at every call site that renders that thing — don't assume one supersedes the other, and don't assume fixing it once means every other render site is also fixed.

Verify: grep every consumer of the field name (and near-miss siblings, e.g. _li_/_field suffixed variants) before trusting that a config toggle does what its label says.

17) SWR await after a write does not mean dependent caches are fresh

Impact: a value you just saved appears stale or "one save behind" immediately after saving — looks like inverted/random behavior when toggling a boolean back and forth, since being one step behind on a 2-state toggle looks exactly like being inverted.

What happened: A save handler awaited load_ae_obj_id__event() (SWR) and assumed that meant Dexie now had the fresh record. In reality the fast path returns the stale cache immediately and refreshes Dexie via a non-awaited background fetch. A different page's own sync $effect read Dexie before that background fetch landed, re-syncing from the stale record and overwriting a value that had just been set correctly moments earlier.

Rule: After a write whose result other reactive code depends on, don't rely on an awaited SWR reload to mean downstream caches are updated — for any call with a populated cache, it almost never is. Update dependent local state directly from the data you already have (what you just saved), not by waiting on a refetch. See the "try_cache: false Bug" section of GUIDE__SvelteKit2_Svelte5_DexieJS.md for the related, equally counter-intuitive case where disabling caching also disables the very write you wanted.

18) Conditional ("locked") sync gates are effectively undebuggable

Impact: a field's local value silently depends on the history of an unrelated flag's state across past syncs, not its current value — looks like inconsistent behavior tied to permission level, browser, or test sequence, none of which is the actual cause.

What happened: sync_config__event_pres_mgmt() only applied a subset of fields when a separate lock_config flag was true at that exact sync call. Toggling lock_config off even briefly during testing froze those fields at stale values in every browser that synced during that window, with nothing in the UI indicating staleness. Removed entirely — every event already had it set to true in production; the conditional gated nothing real.

Rule: Avoid making one config field's sync conditional on another field's current value unless that's a genuine, deliberate design choice — and if it is, surface the dependency in the UI (disable the inputs, show a warning), don't bury it in a silent function-level gate.

Verify: Before adding if (some_flag) { ...many field syncs... }, check whether removing the gate (sync unconditionally) loses any real behavior — query production data for whether the gate is ever actually in the "off" state before assuming it needs to exist.

---

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