Software Updates

light theme client view, navy accents, wireframe off, defaultMetal picker

• ClientViewPage: white background, black logo centered, remove 'Private design preview', light cards
• ClientViewPage: approval panel/buttons light themed, discussion section renamed + light
• STLViewerCanvas: add initialMetal + hideWireframe props
• ClientViewPage: wireframe hidden, initialMetal wired from meta.defaultMetal
• Main share page: remove all dark: classes, replace violet accents with #0b1527 navy
• Main share page: new header with Katura logo (black, centered) + project title
• ShareMeta type: add defaultMetal field
• Prisma: add defaultMetal String? to JewelryProjectShareLink
• Admin share dialog: default metal picker dropdown (yellow-gold, rose-gold, platinum, etc.)
• Share API (GET + POST): wire defaultMetal through
• Migration: prisma/add-share-default-metal.sql + run-share-metal-migration.mjs

chat pushes layout, mic/cam derived state, subtitle top default + position toggle, 2-col translation panel, Option B tightening, subtitleAtTop setting

Katura navy UI, resizable subtitle panel, fix speaker name bar, fix STT alone-in-meeting, rounded video tiles

suppress acoustic-echo mislabelling, green Join Meeting button

host STT client-side init, subtitle floating box, chat polling fallback, condensed default font

add 'YOUR DESIGN IS READY' banner at top of client preview

• Added prominent serif heading above the project title with matching gold divider for premium feel

enlarge logo + make white for better contrast

• Logo height h-8 → h-12 (50% larger)
• Add brightness-0 invert filter to convert gold logo to white on dark background

fix 3D viewer broken prop name in client preview

• STLViewerCanvas only accepts 'url' but the client view was passing 'fileUrl' and 'fileType',
• causing url=undefined and an immediate render failure. Changed to url={activeCad.previewUrl || activeCad.fileUrl}

logo image in client preview header + dialog scrollable layout

• Replace 'KATURA' text with actual logo image (/brand/header-logo.png)
• Share dialog: narrower max-width, proper flex column layout with sticky header and scrollable body
• Existing links section now fully visible without content clipping

support modern webhook event types

• Made webhook payload types flexible to handle both legacy and modern ShipStation events
• Events are now matched by substring (ship/order) instead of exact enum values
• Supports modern event names like 'Sales Orders Imported'
• Unknown events logged for debugging instead of rejected
• Fixes issues with newer ShipStation plans that use different event naming

make apiSecret optional, support API-Key header auth

• ShipStation modern API uses API-Key header instead of Basic auth
• apiSecret is now optional; placeholder value treated as absent
• Falls back to API-Key header when no valid secret configured
• Fixes 401 Unauthorized errors on cron, webhook, and dev test routes
• Checkout live rates (/api/shipping/calculate) now unblocked

subtitle panel redesign, close buttons, cost guard fix

• New SubtitlePanel component: scrollable section below video with side-by-side original/translation
• Speaker names shown for all lines (finalized + live/interim)
• Host subtitles now working (fixed React state race condition with imperative DOM refs)
• Brain icon consistent on both host and guest (replaced Captions icon)
• Yen Advisor always visible on host control bar (consent still gated for CONSULTATION)
• Guest subtitles now receive host captions via LiveKit DataReceived
• Interim translation on guest side (debounced, ~200ms, token-cancelled)
• Font/size/caps customization on guest side (mirrors host settings)
• Close buttons (×) on all floating panels: invite, screen share picker, subtitle settings, language picker
• Cost guard: silent on missing YenTokenSpend table (no more Vercel log spam)
• Added run-yen-token-spend-migration.ts script for idempotent table creation

invite URL trim, faster join, toast on AI Notes start

• invite/route.ts: .trim() NEXT_PUBLIC_APP_URL to strip trailing newline that was producing 'https://katura1999.com\n/g/...' links with a space when pasted in WhatsApp
• join/route.ts: merge two sequential SELECT queries into one to save a DB round-trip on every join (~20-40ms off the join latency). Falls back to the legacy two-pass approach if the single query errors (old schemas).
• meeting-room-client.tsx: show a success toast when AI Notes auto-starts on connect, so the host gets clear feedback that transcription is running

auto-start STT on connect + log transcript save failures

• initialSubtitlesOn = true so Brain/AI Notes is always on for the host
• Add useEffect that calls startStt() once room reaches Connected state (sttAutoStarted ref prevents double-fire on reconnect events)
• Replace silent .catch(() => {}) on both transcript POST calls with console.warn so failures appear in Vercel function logs
• Root cause of 'No transcript segments': host never clicked Brain button for English-language meetings (isNonEnglish was false)

job-queue cron gracefully skips when Upstash Redis not configured

• The cron was throwing a 500 on every run because UPSTASH_REDIS_REST_URL and
• UPSTASH_REDIS_REST_TOKEN are not set in Vercel. Changed getRedisClient() to
• return null instead of throwing, and added an early-return 200 response so
• Vercel does not log a cron failure when Redis is not provisioned.

enforce connection_limit=1 in Prisma singleton to prevent pool exhaustion

• Supabase PgBouncer runs in TRANSACTION mode
• Connections return to the pool after each SQL transaction automatically
• No need for $disconnect() in route handlers — PgBouncer handles it
• This is the official Supabase + Prisma + serverless recommendation
• 400+ route handlers — manual per-route cleanup is not the solution
• Unnecessary with connection_limit=1 + PgBouncer transaction mode
• Creates more connection churn, not less

Correct Nivoda GraphQL schema - price is scalar, all grading under certificate

• Top level: id (offer ID), price (scalar), markup_price (scalar)
• Under diamond: availability, NivodaStockId, certificate (object)
• Under certificate: lab, certNumber, shape, carats, clarity, color, product_images, product_videos
• Fixed DIAMOND_FIELDS GraphQL query to match actual schema
• Updated TypeScript types: removed NivodaDiamondPrice, added NivodaDiamondCertificate
• Updated diamond search component to access certificate data correctly
• Changed price access from d.diamond_price?.price to d.price

add database health check + graceful fallback for connection pool errors

connection pool exhaustion in new arrivals cache + add twitter CSP domains

productview entrypage and exitpage schema type - string not boolean

update nivoda schema fix with final enum and structure corrections

nivoda diamonditem schema - correct nested structure and enum handling

add nivoda graphql schema fix documentation

nivoda diamond graphql schema mismatch - update field names and structure

add incident report for P1 infrastructure failure (May 11 05:00 UTC)

brevo product URL mapping + connection pool cleanup

• Products were syncing with invalid URLs to Brevo
• Caused 110+ product sync failures with '400 Invalid product URL'
• Root cause: URL path mismatch (didn't exist in app)
• Fix: Use correct route /[locale]/products/[slug]
• Prevents database connection pool exhaustion
• Caused P1001 errors on /admin/support page load
• Fix: Call db.$disconnect() in finally block

meetings admin page pagination + search (load 10 initial, add load more button)

Standardize all cron auth patterns and add comprehensive health monitoring

• x-vercel-cron: 1 header (Vercel managed crons)
• ?secret=${CRON_SECRET} query param (manual triggers)
• x-cron-secret header (custom integrations)
• Added cron health tracking: monitors recent errors, status, schedule
• Enhanced database health: detects P2024 connection pool exhaustion
• Added service tracking: Brevo, LiveKit in addition to existing services
• Health endpoint now shows:
• Overall system status
• All external services status
• All cron jobs recent error count
• Database connection pool status
• Last check timestamps
• Track up to 5 recent minutes of cron errors
• Distinguish between temporary (recovering) and persistent (failing) issues
• Pool exhaustion detection (P2024 errors flagged)
• Per-cron error counts help identify problem crons
• Email scheduled 401 errors (auth logic)
• Openclaw reclaim 200 with error logs (auth + error handling)
• Email snooze 401 errors (auth logic)
• No visibility into cron failures (now tracked in health endpoint)

Add Prisma connection pool retry middleware and support escalation cron hardening

• Add Prisma middleware to automatically retry queries on P2024 (connection pool timeout)
• Retry logic: exponential backoff 50ms, 100ms, 200ms (3 attempts)
• Handles Supabase pooler connection limit (10 connections) with 20s timeout
• Prevents cascading failures when pool is temporarily exhausted
• Product page P2024 timeouts (connection pool exhaustion)
• Support escalation 401 errors (auth logic)
• Support escalation 500 errors (database connectivity)

Resolve cron 500 errors and database connectivity issues

• 204 No Content means empty body per HTTP spec
• Response.json() always adds body, violating the spec and causing 'Invalid response status code' error
• Must use: new Response(null, { status: 204 })

Fix cron 500 errors, meeting grace period bug, and guest invite slowness

critical cron routes throwing 500 errors instead of 204

• Added missing `maxDuration = 20` export
• Removed broken `requireKaturaAdmin()` call (was causing 401 → 500)
• Fixed error handler to return 204 instead of 500 (prevents retry cascade)
• Kept kill switch and Brevo timeout protections
• Status: Still running every minute as expected, now returns 204 on errors
• Added missing `maxDuration = 30` export (Vercel free tier: 60s limit)
• Added kill switch: FEATURE_CRON_CONSULTATION_REMINDERS (default: false)
• Added Brevo timeout wrapper (3s Promise.race)
• Fixed error handler to return 204 instead of cascading
• Per-tick cap already in place (50 reminders max)
• Fixed variable shadowing bug (livekitTimeout Promise shadowing counter)
• Renamed Promise to livekitTimeoutPromise for clarity
• Fixed error handler to return 204 instead of 500
• Have explicit `maxDuration` configured
• Return 204 on errors (prevents Vercel retry cascade)
• Are killed if they timeout (Promise.race wrappers)
• Have kill switches to disable safely (except zombie sweep, which is already hardened)

add comprehensive infrastructure hardening sprint summary

• Kill switch (FEATURE_* env, default: false)
• Hard timeout (Vercel maxDuration explicit)
• API/DB timeout (Promise.race, 2-3 seconds)
• Per-tick cap (LIMIT/take clauses)
• State logging (duration_ms + error context)

harden /api/cron/meetings-zombie-sweep with kill switch + timeouts

• Raw SQL query has no timeout
• deleteRoom() call to LiveKit has no timeout
• If either is slow, entire cron hangs up to 20s
• Disabled by default
• Fast 204 return if disabled
• Limit 100 results per query
• Fail fast on slow database
• Each meeting update wrapped
• deleteRoom() fails fast instead of hanging
• Track timeout count separately
• All responses include duration_ms
• Timeout errors logged with context
• Tighter constraint

harden /api/cron/blog-publish with kill switch + DB timeout

• Prisma queries (findMany, updateMany) have no timeout
• If DB is slow or connection pool exhausted, entire cron hangs
• Hits Vercel maxDuration: 20s limit every time
• Creates retry storm on cascading infrastructure
• Disabled by default
• Enable via env var
• Fast 204 return if disabled
• Both findMany and updateMany wrapped
• Fail fast instead of hanging
• Log timeout errors with context
• Limit work per invocation
• Prevents unbounded queries
• Monitor performance trends
• Detect slowdowns early
• Actionable error messages
• Timeout vs. DB error distinction
• Kill switch first ✓
• Hard timeout (Vercel maxDuration: 20) ✓
• DB timeout (2s Promise.race) ✓
• Per-tick cap (LIMIT 50) ✓
• State logging (start/duration/errors) ✓

update crash prevention framework with recent fixes

harden /api/admin/email/scheduled with kill switch + timeout

• Cron runs every minute (1,440x/day) sending emails via Brevo
• Brevo API calls have no timeout
• If Brevo is slow, entire cron hangs for full 20-second maxDuration
• Results in 504 errors every minute, Vercel retry storms
• Cron disabled by default
• Enable deliberately via env var
• Fast 204 return if disabled
• All Brevo API calls wrapped
• Fail fast instead of hanging
• Logged timeout errors with context
• Max 10 emails processed per invocation
• Log start, duration, skip reasons
• Distinguish between timeout vs. API error
• Don't lose failure information
• Kill switch first ✓
• Hard timeout (implicit via Vercel maxDuration: 20) ✓
• External API timeout (3s Promise.race) ✓
• Per-tick cap (LIMIT 10) ✓
• State logging (start/duration/errors) ✓

document Next.js routing conflict root cause & fix

resolve critical Next.js routing conflict in /admin/invoices

• [id] directory
• [orderId] directory
• Moved /api/admin/invoices/[orderId]/ to /api/admin/invoices/[id]/actions/
• Updated route.ts to use 'id' parameter (destructured as orderId internally)
• Updated documentation comments to reflect new URL pattern

add crash prevention framework overview

• Why each document exists
• How to use them (3 scenarios: new cron, investigation, cost reduction)
• The 5 blast-door rules (kill switch, schema drift, no minutely fan-out, fast-fail, state logging)
• Implementation timeline (4 phases over 2 months)
• The bottom line: optimize for crash-proofing, not cost savings

transform cron analysis into hardened policy with teeth

• Kill switch first (before Prisma/APIs)
• Hard timeout on all routes
• External API timeouts (Promise.race)
• Idempotent operations
• Per-tick caps (LIMIT/MAX)
• Claim/lease pattern before expensive work
• New tables require migration gates
• Default-disabled for new crons
• No minutely AI workflows
• Fast-fail on missing dependencies
• State transition logging
• Never be the first path to discover schema drift
• Level 0: Static/no dependency (5–10 min OK)
• Level 1: DB read-only (5–15 min OK)
• Level 2: DB writes/notifications (5–15 min OK)
• Level 3: External APIs (10–30 min, business-critical allows more)
• Level 4: AI/agents/automation (NEVER minutely without queue + cap + meter)
• Migration exists
• Applied to production
• Verified in prod
• Feature flag disabled until verified
• Handles missing table gracefully
• Rollback path documented
• The hard rule: 'A cron route must never be the first production code path to discover a missing table.'
• Marked as 'NEEDS IMMEDIATE REDESIGN' (not just frequency reduction)
• Architectural issue: admin routes shouldn't contain cron logic
• Action plan: rename to /api/cron/email-scheduled, add feature flag, per-tick cap, timeout, deduplication, claim pattern, retry counter
• Corrected 'Consider reducing to hourly if queue backed up' to 'Consider INCREASING to hourly only if backed up AND response < 10s'
• Added clarification: 'Increasing frequency means MORE load when backed up'

add root cause + cron analysis to postmortem

• /api/admin/email/scheduled: EVERY MINUTE (1,440x/day) — too aggressive
• /api/cron/meetings-zombie-sweep: */5 (288x/day) — LiveKit dependency
• /api/cron/calendar-reminders: */10 (144x/day) — calendar API dependency
• /api/admin/email/snooze: */5 (288x/day) — unnecessary frequency
• /api/cron/blog-publish: */5 (288x/day) — not user-facing
• /api/health?ping=true: */5 (288x/day) — overkill for health check
• Reduce email/scheduled from minutely to */5 or move to event-driven
• Reduce 5-minute jobs to */10 (except critical paths)
• Add 2–5 second timeouts to all crons to prevent hangs
• Add metrics + logging to detect issues early

completely delete yen-heartbeats cron

• Deleted src/app/api/cron/yen-heartbeats/route.ts
• Removed cron entry from vercel.json
• Updated postmortem with complete removal notes
• Queue-based dequeue model (one heartbeat per minute)
• Atomic state transitions (claim before work)
• Per-heartbeat timeout (10s max)
• Single-heartbeat cap (MAX_FIRES_PER_TICK = 1)
• Comprehensive logging + metrics
• Chaos test suite

disable cron + postmortem

• Unbounded fan-out: no cap on heartbeats per tick
• Missing overlap guard: checked nonexistent updatedAt field
• State written too late: lastFiredAt updated after completion
• Each failure created duplicate invocation in next minute
• 1.5K invocations in 2 hours, 46s P75, 100% error rate
• Cascaded to notifications (79% error), admin pollers (99% error)
• Peak burn: ~/day run rate on Fluid Compute
• Redesign as dequeue (process one heartbeat per minute)
• Add application-level logging + metrics
• Write chaos tests (Claude API timeouts, etc.)
• Soft launch at 5-minute intervals
• Monitor 24h before re-enabling at full schedule