7.5 KiB
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
TypeErrorand 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.
- Bad
.d.tsmodule declaration masking errors (important incident, low recurrence recently). - Launcher
file_purpose == 'admin'filtering gap (specific historical enum-audit miss). - 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.mddocumentation/TODO__Agents.mddocumentation/GUIDE__SvelteKit2_Svelte5_DexieJS.mddocumentation/GUIDE__AE_API_V3_for_Frontend.mddocumentation/PROJECT__Stores_Svelte5_Migration.md