RAID Report — 2026-04-28
Date: 28-04-2026 Subject: RAID Report
Source: docs/architecture/RISKS_GAPS_ASSUMPTIONS.md (main branch — last updated 2026-04-26 per Change Summary). Previous report: RAID_REPORT_2026-04-25.md (3 days ago).
| Issue Number | Issue Type | Status | Days Open | Suggested Action |
|---|---|---|---|---|
1. Monolithic UI/control plane (src/App.jsx ~500 lines, owns auth gates, layout, route tree, prop fan-out) | Risk | Open | Unknown (predates 2026-04-23) | Begin v1.1 refactor — split into focused screen components + a dedicated routing module; lift modal/overlay refs into a context. |
2. Oversized hooks acting as service layers (useNoteForm ~470 lines, useSettings) | Risk | Open | Unknown (predates 2026-04-23) | Decompose into UI-state hook + pure persistence module + ingest/PostHog dispatcher; add unit tests around the seams. |
| 3. | Risk | Closed (resolved per 2026-04-26 audit — useAuth.js:175 only sets the flag after success) | n/a | None — verify regression coverage in next sync test pass. |
| 4. Manual Supabase migration application — drift detection automated but apply still manual via SQL editor [SUR-60] | Dependency | Open | Unknown (predates 2026-04-23) | Add a CI gate that fails the build if scripts/check-schema.js reports drift on main; longer-term, adopt Supabase CLI db push from CI. |
5. Managed proxy env fragility — missing SUPABASE_SERVICE_ROLE_KEY / ANTHROPIC_API_KEY surfaces as generic 500s with no operator detail in the user toast | Dependency | Open | Unknown (predates 2026-04-23) | Add a startup self-check Edge Function that pings each required env at deploy; route 500s to a structured error code surfaced in the toast for ops. |
| 6. | Risk | Closed (SUR-91 fully sunset; only a one-time apiKey meta cleanup remains in db.js:156) | n/a | None — schedule removal of the cleanup shim once telemetry confirms no remaining BYOK rows. |
7. No per-note image cleanup — note-images bucket retains orphans after note delete (per-account sweep only on full account deletion) | Gap | Open | Unknown (predates 2026-04-23) | Mirror deleteCloudData’s sweep into cloudWrite for soft-deleted notes; add a nightly orphan-blob job comparing notes.imagePath to the bucket. |
8. fetchSince helper unused [SUR-62] | Gap | Closed (fetchAllCloud(since) now wired through lastSyncRef.current with backfill in useAuth.js:189-210) | n/a | None — keep the backfill regression covered by incremental-sync.test. |
9. Outbox single queue, opaque failure mode — one stuck payload (RLS reject, oversized sourceMeta) blocks the rest; user sees no quarantine surface | Risk | Open | Unknown (predates 2026-04-23) | Split the outbox by entity type or add a poison-message quarantine + a Settings panel that lists stuck items with retry/discard actions. |
10. callTranscribeImage | Gap | Closed (covered by api.test.js, photoAdapter.test.js, capture.test.jsx) | n/a | None. |
| 11. Accessibility gaps — long-press only for edit/delete, no keyboard / context-menu / visible button alternative; bottom-nav-hidden state on capture/note compounds it | Gap | Open | Unknown (predates 2026-04-23) | Add a visible “more actions” overflow button on note rows + keyboard shortcuts; document target sizes against WCAG 2.5.5. |
12. Usage opacity — ai_usage_daily not surfaced; users only see “Monthly limit reached” toast at the cap | Gap | Open | Unknown (predates 2026-04-23) | Add a usage meter (“X / 1000 calls this month”) in ProfileScreen or SettingsModal, sourced from ai_usage_daily. |
13. /#faq, /#what-is-surfc resolve to nothing post-SUR-218) | Risk | Closed (SUR-223 Phase 1 — ProfileScreen and SettingsModal now point to https://help.surfc.app) | n/a | Phase 2 (in-app help renderer reading from docs/getting-started/) remains outstanding — track separately. |
| 14. | Risk | Closed (already in prior report) | n/a | None. |
| 15. Dexie ↔ Supabase lockstep is human-driven — Dexie v1→v9 migration chain not cross-checked against the schema contract | Assumption | Open | Unknown (predates 2026-04-23) | Extend scripts/check-schema.js to also assert Dexie’s expected columns; add a PR template item for “Dexie + Supabase + mergeCloudRecords updated together”. |
| 16. Free-tier 1000-call/month managed quota is sufficient; per-tier pricing deferred [SUR-67] (was 30/month in prior report — corrected per 2026-04-26 audit) | Assumption | Open | Unknown (predates 2026-04-23) | Pull token-cost data from ai_usage_daily.input_tokens/output_tokens into a simple weekly cost dashboard; revisit once paid tiers land. |
17. VitePWA autoUpdate is acceptable — no onNeedRefresh UI; users won’t be told a new version exists | Assumption | Open | Unknown (predates 2026-04-23) | Wire a registerSW({ onNeedRefresh }) toast with a “Reload” CTA; combine with fix for deprecated apple-mobile-web-app-capable meta. |
| 18. Cascading book + note tombstones acceptable despite orphan-image risk on failed image-upload races | Assumption | Open | Unknown (predates 2026-04-23) | Same fix as #7 — once orphan-image sweep exists, this assumption can be retired. |
19. Future ingest adapters (Readwise / Kindle) reuse the existing ingest interface without backend changes | Assumption | Open | Unknown (predates 2026-04-23) | Build a Readwise PoC against the current adapter to validate; if backend changes are needed, surface them before adapter v2 lands. |
20. CaptureFabMenu speed-dial provides sufficient navigation on capture/note views with bottom-nav hidden [SUR-238] | Assumption | Open | 5 (added 2026-04-23) | Run a 5-user usability test on capture → save → return-to-library; if friction shows, add a persistent back affordance. |
21. How are Supabase credentials and ANTHROPIC_API_KEY managed in Netlify and Supabase Edge environments — and what is the rotation cadence? | Dependency | Open | Unknown (predates 2026-04-23) | Document the secret-management process in docs/architecture/DEPLOYMENT_ARCHITECTURE.md; agree a rotation cadence (90 days) and put a calendar reminder. |
22. Monitoring / alerting for sync failures and Edge Function errors — console.log-based, not piped to PagerDuty / Slack / email | Gap | Open | Unknown (predates 2026-04-23) | Add a Logflare or Logtail drain on the Edge Functions; alert on >N 5xx/min and on decrypt_failure PostHog event spikes. |
| 23. Should exports include Supabase storage paths or binary blobs to guarantee a fully portable backup? | Gap | Open | Unknown (predates 2026-04-23) | Add an opt-in “Include images” toggle to buildExport; emit a zip with JSON + image blobs when enabled. |
24. SLA for clearing orphaned note-images on still-active accounts (deleted notes, replaced images) | Gap | Open | Unknown (predates 2026-04-23) | Define a 7-day orphan window; bundle into the same nightly sweep proposed in #7. |
25. Multi-device editing conflict UI beyond last-write-wins not surfaced — mergeCloudRecords silently picks higher updated_at | Gap | Open | Unknown (predates 2026-04-23) | Log conflicts to a local audit table; surface a “Your edit was overwritten” toast with a “Restore my version” link. |
26. Background sync (service-worker sync events) for queued writes when app is closed | Gap | Open | Unknown (predates 2026-04-23) | Register a background-sync event in the VitePWA service worker; gate behind a feature-flag for browsers that support it. |
27. Edge Function debug logs include user_id on every authenticated request — broader audit trail than the rest of the app | Risk | Open | 2 (added 2026-04-26) | Strip or hash user.id in anthropic-proxy/index.ts:399-400, 423; keep only error-path logs at warn/error level. |
28. Rate-limit race window — getMonthlyUsage check and recordUsage write are not atomic; documented worst-case overrun equal to in-flight requests [TODO SUR-67] | Risk | Open | 2 (added 2026-04-26) | Move enforcement into a CHECK on the upsert_ai_usage RPC, or wrap in a SELECT … FOR UPDATE; revisit once paid tiers land. |
29. Full re-decrypt on every sync — loadAll(decryptFn) re-decrypts every encrypted note text after each merge; sync time scales linearly with library size | Risk | Open | 2 (added 2026-04-26) | Build an encryption-only delta path keyed off updatedAt; batch decrypts with a Web Worker; add a progress indicator. |
30. Sync image fetch is sequential — for loop, O(N) round-trips on a fresh device; failures silently swallowed | Risk | Open | 2 (added 2026-04-26) | Parallelise with Promise.allSettled and a small concurrency limit (e.g. 6); surface per-image failures as a retry list. |
31. Decrypt-failure recovery is dead-end — flagged with decryptError: true, no UI retry path beyond full sign-out, no count surfaced to user | Gap | Open | 2 (added 2026-04-26) | Add a “Decryption issues” panel in Settings showing affected count + a “Retry unlock” button that re-runs getEncryptionPrfOutput. |
| 32. Transfer-code auto-expire is best-effort — 60 s deactivation upsert can fail silently, leaving wrapper active until next create cycle | Risk | Open | 2 (added 2026-04-26) | Add a server-side scheduled job (Supabase pg_cron) to deactivate transfer-v1 blobs older than 90 s; alert on backlog growth. |
33. No PWA update prompt — VitePWA autoUpdate with no onNeedRefresh UI; iOS standalone install path most exposed | Risk | Open | 2 (added 2026-04-26) | Same fix as #17 — implement onNeedRefresh toast and update the deprecated meta tag in index.html. |
34. db.js has no dedicated unit tests — CRUD helpers and v1→v9 Dexie upgrade chain only covered transitively | Gap | Open | 2 (added 2026-04-26) | Add src/test/db.test.js covering each migration step + cascade behaviours; add a CI gate that runs migration replay against a fixture DB. |
| 35. Duplicate-source UX gap [SUR-257] — duplicate hint is non-blocking, no merge / de-dupe path; orphan sources accumulate | Gap | Open | 2 (added 2026-04-26) | Make the hint a confirm-step (“Looks like a duplicate — Use existing / Create anyway”); add an admin de-dupe tool in Settings. |
36. Branded auth-email template lives in repo only [SUR-261] — magic-link.html must be manually pasted into Supabase dashboard with no CI sync | Gap | Open | 2 (added 2026-04-26) | Add a scripts/sync-auth-templates.js using the Supabase Management API; gate on a manual approval but make it one command. |
37. Approved waitlist rows with user_id IS NULL stranded for email-OTP [SUR-261] — match_waitlist_on_signup only back-fills on auth.users INSERT and OTP refuses shouldCreateUser:false | Gap | Open | 2 (added 2026-04-26) | Add a nightly job that runs the audit query (status='approved' AND user_id IS NULL) and auto-sends Supabase invites; alert on backlog. |
38. Email-OTP error-string mapping is best-effort [SUR-261] — relies on Supabase Auth’s Signups not allowed for otp substring staying stable | Assumption | Open | 2 (added 2026-04-26) | Add an integration test that pings the live Supabase Auth response for an unknown email and asserts the substring; alert on regression. |
39. Email signups stay disabled at the Supabase platform level — requestEmailOtp pins shouldCreateUser:false as defence-in-depth | Assumption | Open | 2 (added 2026-04-26) | Document the dashboard toggle state in DEPLOYMENT_ARCHITECTURE.md; add a check to scripts/check-schema.js that asserts the auth config. |
| 40. Email-OTP code length and expiry are Supabase defaults (6 digits / 1 hour) | Assumption | Open | 2 (added 2026-04-26) | Acceptable for personal scale; revisit if abuse signals appear (failed-attempt rate-limit telemetry). |
41. isStandaloneOrTwa() decides OTP-code vs magic-link delivery once at component mount [SUR-261] — no hot-swap mid-session | Assumption | Open | 2 (added 2026-04-26) | Acceptable today; add a comment in src/lib/platform.js explaining the constraint and revisit when iOS/Android expose surface hot-swapping. |
42. Cross-domain help.surfc.app (Cloudflare Pages) remains reachable from authenticated app shell links — no in-app fallback if DNS / cert / Pages outage | Assumption | Open | 2 (added 2026-04-26) | Phase 2 in-app help renderer (already on backlog) addresses this; add a temporary fallback message on link click. |
43. session.access_token expiry handled by getSession() calling _callRefreshToken immediately before each Edge Function invoke | Assumption | Open | 2 (added 2026-04-26) | Add a regression test that simulates a backgrounded-PWA “Invalid JWT” and asserts the refresh path fires. |
44. ANTHROPIC_API_KEY rotation is a manual operator task — no client-side hint of expiry; rotated-then-misconfigured key surfaces as blanket 500 | Assumption | Open | Unknown (predates 2026-04-23) | Same fix as #5 — startup self-check Edge Function with structured error codes. |
45. Project-level Anthropic spend cap unknown — only per-user ai_usage_daily counters; no automated alert | Dependency | Open | Unknown (predates 2026-04-23) | Set a project-level monthly cap in Anthropic Console; pipe spend metrics into PostHog or a weekly digest email. |
| 46. Account recovery without passkey + no transfer code — data unrecoverable by design; copy points to “the device where you originally enabled encryption” | Gap | Open | Unknown (predates 2026-04-23) | Document this as a deliberate trade-off in the help site; consider an opt-in “recovery key” downloaded at enrolment for users who accept the risk. |
47. Deletion-success audit trail beyond in-flight delete-account 200 response — if auth.admin.deleteUser succeeds but client crashes before finalizeAccountDeletion, user sees stale session | Gap | Open | Unknown (predates 2026-04-23) | Add a server-side account_deletions audit table written inside the Edge Function transaction; reconcile on next sign-in attempt. |
Summary
- 47 items total in the new report (up from 26 in the 25-04-2026 report).
- Closed since last report: 4 items struck through — #3 (SUR-61 schema probe), #6 (SUR-91 BYOK), #8 (SUR-62 full-table sync), #10 (OCR regression coverage), plus #13 (SUR-209 in-app help links — resolved by SUR-223 Phase 1). #14 (How-It-Works placeholders) remained closed from the prior report.
- New items added since 2026-04-26 audit: 21 items (#27–#47), reflecting the codebase-wide audit on 2026-04-26 and the SUR-261 email-OTP work. Each carries 2 days open.
- Corrected since prior report: #16 — managed quota is 1000/month (not 30); the previous report carried a stale figure.
- By type: 11 Risks, 16 Gaps, 4 Dependencies, 11 Assumptions, plus 5 Closed.
- Days-open precision: Items dated 2026-04-23 (#13, #20) → 5 days; items dated 2026-04-26 (#27–#43) → 2 days. Pre-2026-04-23 items still report
Unknownbecause the source document does not record a per-item Logged date — same caveat as the prior report.
Notes / autonomous decisions
- Read the file from
main(current branch isfeat/sur-242-prompt-fencing, but the task explicitly asked for the main-branch version — usedgit show main:docs/architecture/RISKS_GAPS_ASSUMPTIONS.md). - Classification: same scheme as the prior report — capability/coverage missing → Gap; external requirement that could break things → Dependency; future event/condition that could damage the product → Risk; “Key assumptions to validate” entries → Assumption. Open Questions in the source were classified as Gap or Dependency depending on whether the unknown is internal (gap) or third-party (dependency).
- “Closed” items are kept in the table with strikethrough and
n/adays, per the task spec (“Mark these by crossing them out in the report”). - New items inherit a “days open” count derived from the Change Summary date in the source, since the file still does not record a per-item Logged date.
- Suggested actions are intentionally concrete and ticket-sized; they are suggestions, not commitments.
- Delivery: task asked for the report to be sent to a chat in the Surfc project on claude.ai. The Chrome MCP extension was not connected at run time, so auto-delivery wasn’t possible in this run. The report has been saved to
docs/architecture/RAID_REPORT_2026-04-28.md(and a copy in the session outputs folder) so it can be pasted into the chat manually, or auto-posted on the next run if the Chrome extension is connected.