Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / convex-schema-and-jobs

Convex schema and scheduled workflows

Convex is the durable state and job layer for World Monitor. It stores account, preference, access, billing, monitoring, usage, feedback, alert, and delivery state. It also runs trusted work after a request or on a schedule so important actions can resume after a timeout or lost browser session.

This page gives the backend view of application state. For identity gates and subscription access, see access control and subscriptions.

Convex service boundary

Convex joins product state to backend work. Public functions serve signed-in product surfaces. Internal functions serve trusted relays, provider webhooks, operators, workers, and scheduled jobs.

The boundary derives user scope from server-side identity. It keeps provider calls in actions and database changes in mutations. HTTP routes authenticate trusted callers before they pass a narrow request to an internal function. This separation keeps external systems from writing arbitrary tenant data while still allowing the edge and workers to use durable state.

Function roles

Queries give clients and workers read views of current state. Mutations validate input and change related rows in one transaction. Actions call external services or coordinate work that needs more than one database step. Scheduled functions start or continue work that must outlive one request.

The generated API describes the public and internal function names used by these callers. It is a contract for callers, not a second source of state.

References: convex/…/api.d.ts• L106-195 convex/…/api.d.ts• L205-221 convex/http.ts• L100-119

Identity and write fences

Authenticated reads and writes resolve the current Clerk identity on the server. Internal callers pass an explicit user or account only after a trusted route has checked its role. Account deletion adds a write fence so personal state cannot be recreated while cleanup is in progress.

Provider identity is trusted only when it has a durable link or a server-made signature. The same rule protects checkout ownership, invite acceptance, anonymous purchase claims, and notification-channel ownership.

References: convex/…/erase.ts• L79-185 convex/notificationChannels.ts• L223-281 convex/http.ts• L94-119

Durable state model

The schema groups rows by product purpose. Indexes support the lookups needed for user ownership, provider identity, time windows, event deduplication, access, delivery health, and job progress. The state records both the current answer and enough history to retry work or explain a decision.

State areaProduct purposeDurable result
Account and preferencesKeep a user's settings and account factsIdentity, profile, locale, time zone, preferences, terms, and language choices
Alerts and deliverySelect and send relevant eventsRules, country and market scopes, delivery endpoints, attempts, failures, suppression, and digest state
Watchlists and summariesPreserve user selections and shared countsFollowed countries, aggregate counts, serialization rows, and migration markers
Team collaborationLet Business and Enterprise members share monitoring viewsTeam-owned dashboard layouts with versioned updates and access-aware focus settings
Access and billingTurn payment or contract coverage into product accessSubscriptions, customers, payments, entitlements, grants, and contract members
External credentialsSupport API, desktop, embed, and MCP accessHashed or opaque credentials, scopes, revocation, and last-use state
Usage and customer noticesEnforce limits and explain plan stateUsage rollups, notice state, source freshness, and upgrade targets
Product workflowsPreserve work that spans requestsCheckout funnel, activation records, feedback, broadcasts, and job leases
Intelligence and monitoringPreserve history and customer-selected monitoringHistorical events, evidence, candidates, decisions, scans, obligations, and purge state
Account lifecycleRemove personal data without losing required billing evidenceDeletion tombstones, stage cursors, retry state, and external cleanup results

References: convex/schema.ts• L120-320 convex/schema.ts• L329-526 convex/schema.ts• L545-731 convex/schema.ts• L735-1057 convex/…/registry.ts• L22-315

Transaction boundaries

Mutations keep related state aligned. A preference or alert change validates its whole shape before writing. An entitlement change records the selected coverage and then schedules cache work. A seat change updates membership and access together. Repeated provider events and client retries are expected inputs, so important writes use an existing identity, a durable marker, or a lock to avoid a second result.

Pre-seeded lock rows make the same guarantee work for aggregate counters and first-write races. A later run can read the committed state and decide whether the requested work is still needed. This design favors a safe retry over exact timing.

References: convex/schema.ts• L329-394 convex/agentFeedback.ts• L151-254 convex/enterpriseAccounts.ts• L103-162 convex/…/businessSeats.ts• L57-83

Watchlist and alert state

Followed countries keep per-user rows, country counts, and shared lock state. This lets a cap and a public count stay consistent when users change the list at the same time. Alert rules can then scope local events to followed countries or to other product-specific selections such as tickers, chokepoints, watched sites, and reservoirs.

Alert scope migration records one durable marker per visited rule. This prevents a later rerun from changing a user's deliberate choice while still allowing the system to notify users about the change in realtime alert behavior.

References: convex/schema.ts• L235-394 convex/alertScopeMigration.ts• L19-29 convex/alertScopeMigration.ts• L57-114 convex/…/alertScopeSeed.ts• L25-58

Campaign state

Campaign state uses durable rows for the ramp configuration, each wave run, and each selected contact. The schedule can therefore pause after a failed external step and resume or recover a wave without treating an in-flight email operation as complete.

References: convex/schema.ts• L436-642

Team dashboard state

Team dashboards add shared application state for teams that monitor the same world view. The dashboard belongs to the resolved Business subscription or Enterprise account rather than to the member who last changed it, so one member can publish a view and another can use it.

Team membership boundary

The dashboard queries derive the caller's team from current server-side access. They prefer a live Enterprise membership, then the caller's own covering API Business subscription, then an accepted Business seat. A signed-out caller or a caller without a team receives no team dashboards.

Focused views are treated as an access-controlled capability. Clients that cannot render focus do not receive focused layouts, while publishing a focused layout requires the caller's current focus entitlement or the team's Business plan. See access control and subscriptions for the broader entitlement model.

References: convex/teamDashboards.ts• L39-80 convex/teamDashboards.ts• L108-127 convex/…/businessSeats.ts• L377-421 convex/enterpriseSeats.ts• L100-143

Shared dashboard lifecycle

The dashboard lifecycle keeps shared views bounded and safe for concurrent editors. A member lists views for a preference variant, creates a new view, updates an existing view against the version last seen, or removes a view from team sharing. The system limits each team and variant to 25 dashboards and keeps removed views out of later lists.

The shared layout is validated before it becomes durable state. It describes panels and optional map and focus settings. Validation rejects malformed panel keys, duplicate entries, unsafe map ranges, invalid country scope, and excessive filter data, so clients can treat stored layouts as trusted product state.

This diagram shows how a member's current team access controls the shared dashboard read and write path.

flowchart LR
    A[Member request] --> B[Resolve live team access]
    B --> C{Team found?}
    C -->|No| D[No shared dashboards]
    C -->|Yes| E[Read or publish team layout]
    E --> F[Validate layout and focus access]
    F --> G[Versioned team dashboard state]

References: convex/teamDashboards.ts• L130-169 convex/teamDashboards.ts• L172-230 convex/teamDashboards.ts• L232-241 convex/…/teamDashboardLayout.ts• L5-40 convex/…/teamDashboardLayout.ts• L42-108

Access and entitlement state

Access is derived from a shared product catalog and durable coverage sources. The catalog defines plan meaning. The entitlement row gives the edge and product surfaces a current view. A user can be covered by a subscription, a Business grant, a complimentary grant, or a live Enterprise contract.

Product catalog and entitlement view

convex/…/productCatalog.ts is the shared vocabulary for plans, features, provider products, limits, checkout visibility, upgrade paths, and alert capabilities. Subscription processing resolves a provider product to a plan and stores its feature view. Reads merge current catalog defaults into older rows so a new feature or limit reaches existing accounts without waiting for another payment event.

The merge treats structural limits as catalog-owned. This includes shared REST and MCP budgets, Enterprise defaults, desktop-key limits, and the alert ladder. The alert ladder gives free accounts a small supported shape while paid plans receive the full alert surface.

References: convex/…/productCatalog.ts• L67-110 convex/…/productCatalog.ts• L218-264 convex/…/productCatalog.ts• L296-357 convex/…/productCatalog.ts• L812-877 convex/…/entitlements.ts• L39-120 convex/…/entitlementFeaturesValidator.ts• L13-87

Alert capability ladder

Alert capabilities are a plan-shaped set of limits for countries, channels, sensitivity, delivery cadence, and AI digest use. The write boundary checks the effective rule after a change, so a free account cannot create a wider rule through a partial update or a second alert variant. The HTTP layer turns a capability denial into a machine-readable response that the client can use to show the right upgrade or setup path.

Free accounts can use a small country-scoped realtime rule with critical events and email or web push. Paid accounts can use the wider country cap, all supported channels, all sensitivity levels, digest cadences, and AI digests. Orbital-site and reservoir alerts remain direct paid capabilities rather than ladder rungs.

References: convex/…/alertCapabilities.ts• L13-76 convex/alertRules.ts• L84-135 convex/alertRules.ts• L356-475 convex/http.ts• L154-224 convex/…/productCatalog.ts• L296-321

Alert scope migration

Realtime rules that had no country scope used to receive local critical events without a place selection. The one-time migration copies the user's followed countries into enabled realtime rules when the current plan allows it. Rules with no followed countries remain marked as global-only, and each visited rule gets one notice row.

The migration runs in pages and separates state changes from notice delivery. Notice sends group all migrated rows for one user, re-read current scope and plan state, honor suppression, and retry only rows that remain pending.

References: convex/alertScopeMigration.ts• L1-29 convex/alertScopeMigration.ts• L57-114 convex/alertScopeMigration.ts• L135-219 convex/alertScopeMigration.ts• L392-470

Coverage selection

Entitlement recomputation reads all current coverage sources instead of copying the event that happened most recently. It selects the strongest live source by plan tier, product precedence, and end time. Paid-through cancellation and payment-hold periods keep access only until their stored end. A later scheduled recheck handles the boundary when another source lasts longer.

The resulting entitlement is the durable access view. Redis is only a short-lived edge cache. A delayed sync reads Convex again before it writes, so an older payment event cannot restore stale access after a newer change.

References: convex/…/subscriptionHelpers.ts• L520-611 convex/…/subscriptionHelpers.ts• L657-786 convex/…/billing.ts• L1217-1231 convex/entitlements.ts• L20-61

Enterprise contract accounts

Enterprise accounts represent operator-managed contracts rather than self-serve subscriptions. Active members share the contract's request pool and AI token allowance. A live member receives Enterprise access until the contract end. The member keeps the contract's provider restriction after the contract ends until an operator removes the membership.

Membership changes recompute access and clear edge caches. Contract start and end each have one scheduled recompute so a boundary takes effect even when no webhook or user request occurs.

References: convex/schema.ts• L977-1037 convex/enterpriseAccounts.ts• L124-187 convex/…/enterpriseAccounts.ts• L32-48 convex/…/enterpriseAccounts.ts• L77-139

Enterprise seat lifecycle

An Enterprise admin can invite corporate email addresses from Settings. A pending invite holds a seat until it expires. The invite link is signed and bound to one member row. Acceptance requires the signed-in email to match, the contract to remain live, and the user not to belong to another Enterprise account.

The account lock serializes seat changes. Removal immediately removes the member's access and routing policy. Email delivery is separate from the membership transaction, so a failed invite remains visible to the admin without undoing the seat record.

The lifecycle is:

flowchart LR
    A[Enterprise contract] --> B[Admin invite]
    B --> C[Pending member]
    C --> D[Accepted member]
    D --> E[Pooled access and limits]
    A -. contract end .-> F[Scheduled recompute]
    F --> G[No live contract access]
    D -. admin removal .-> H[Immediate recompute]
    H --> G

References: convex/enterpriseSeats.ts• L147-241 convex/enterpriseSeats.ts• L244-324 convex/enterpriseAccounts.ts• L103-187 convex/…/identitySigning.ts• L309-367

Business seat lifecycle

API Business seats give a covering Business subscription a small pool of Pro grants. Pending invites count until they expire, accepted grants give the invitee Pro access, and a lapse or owner removal recomputes the invitee's entitlement.

The Business subscription lock protects the seat cap across invite and removal requests. Signed links, corporate-domain checks, verified invitee email, and current subscription coverage keep a grant tied to the intended team and plan.

References: convex/…/businessSeats.ts• L57-123 convex/…/businessSeats.ts• L125-243 convex/…/businessSeats.ts• L425-527 convex/schema.ts• L1100-1222

AI routing policy

AI routing is a separate control from billing features. A per-user policy can limit the providers used for that user's input. Enterprise membership can supply an account policy, and several memberships narrow the result to providers allowed by every account. A policy update clears the short-lived edge cache after the durable write.

Company Monitoring uses a fixed classifier provider. If the active policy excludes that provider, the candidate is rejected before customer evidence reaches classification work.

References: convex/entitlements.ts• L100-180 convex/…/enterpriseAccounts.ts• L107-139 convex/http.ts• L483-518

Product and provider workflows

Convex connects durable product state to providers through signed, idempotent workflows. The common pattern is to authenticate an external event, validate its shape, commit the local state, then schedule any email, cache, or provider follow-up.

Payment and webhook state

Dodo payment events create or update subscription and payment history. The handler resolves ownership from stored provider links or signed checkout metadata. It distinguishes an authenticated but unattributed payment from a processing failure. An unattributed payment is retained for operator repair rather than retried forever.

Subscription changes recompute access from all sources. Unknown product IDs use a visible temporary over-grant and an operator signal instead of failing the webhook and leaving paid access stale. Renewal reconciliation checks Dodo again when a webhook may be missing. It uses bounded pages, backoff, repeated evidence for definitive not-found results, and a circuit breaker so a provider outage does not revoke many accounts at once.

References: convex/…/subscriptionHelpers.ts• L147-183 convex/…/billing.ts• L83-183 convex/…/billing.ts• L1217-1231 convex/http.ts• L312-435

Unattributed payment state

An authenticated Dodo event can be valid while lacking enough ownership data to attach it to a World Monitor account. Convex stores that event as an operator repair row before the webhook is acknowledged. Charged events alert operators at once because the buyer has paid without access; uncharged attempts are grouped by customer to reduce noise.

The repair queue keeps raw evidence for attribution and can replay the event after an operator links it to the correct user. Duplicate webhook IDs update the existing row rather than create a second incident.

References: convex/…/unattributedPayments.ts• L58-163 convex/…/unattributedPayments.ts• L216-291 convex/schema.ts• L269-277

Checkout and billing communication

Checkout admission protects the account and provider from duplicate or excessive session creation. The later webhook joins payment state to the signed checkout identity. The checkout funnel is recorded separately because reaching a hosted payment page is useful even when no payment row follows.

Billing email is scheduled outside the webhook transaction. Welcome, dunning, cancellation, and win-back sends re-check deletion state, coverage, recipient suppression, and a per-episode ledger before sending. This makes a retry safe and keeps a provider delay from blocking payment state.

The checkout-to-notice path is:

flowchart LR
    A[Validated checkout request] --> B[Signed provider metadata]
    B --> C[Payment webhook]
    C --> D[Durable subscription state]
    C --> E[Scheduled billing email]
    E --> F[Customer welcome]
    E --> G[Admin conversion notice]

References: convex/…/checkout.ts• L363-422 convex/…/checkout.ts• L510-579 convex/…/subscriptionEmails.ts• L395-427 convex/…/subscriptionEmails.ts• L529-617 convex/…/subscriptionEmails.ts• L1279-1406

Credential and MCP access

API, desktop, embed, and MCP access use durable ownership records with revocation. Bearer secrets are not returned from ordinary reads. An MCP token identifies a user but does not preserve paid access; each gated request derives current entitlement again. Revoked credentials remain visible as history while edge caches are cleared on lifecycle changes.

References: convex/mcpProTokens.ts• L9-20 convex/mcpProTokens.ts• L31-107 convex/mcpProTokens.ts• L159-218 convex/…/cacheActions.ts• L288-319

Company Monitoring admission

Company Monitoring turns provider findings into customer results through an evidence-bound admission flow. A candidate carries the evidence revision and snapshot used for the decision. A worker lease gives one classifier ownership. The result is accepted only when the candidate, lease, evidence revision, policy versions, and replay identity still match.

The workflow can publish, hold for a later retry, reject, or expire. A stale worker cannot publish a result after the company loses access or the evidence changes.

References: convex/…/admission.ts• L61-120 convex/…/admission.ts• L301-435 convex/…/admission.ts• L437-545 convex/…/admission.ts• L568-661 convex/…/admission.ts• L751-800

Agent feedback workflow

Agent feedback provides a durable intake and triage queue for reports from MCP, RPC, and other agent-facing surfaces. The edge sanitizes and redacts report data before storage. Convex deduplicates retries, limits reporter volume, separates security reports from ordinary feedback, and keeps notification progress independent from triage status.

Security reports can trigger a bounded owner notice. A daily digest covers reports held by the cap or a failed send. Retention depends on status, and filed reports keep only the facts needed to link them to the resulting issue.

References: convex/agentFeedback.ts• L19-85 convex/agentFeedback.ts• L151-254 convex/agentFeedback.ts• L350-373 convex/agentFeedback.ts• L442-503 convex/agentFeedback.ts• L515-650 convex/agentFeedback.ts• L656-775

Scheduled workflow system

Convex cron definitions provide the clock for maintenance, recovery, customer messages, usage checks, retention, and data readiness. A cron starts bounded work. Large work stores progress and schedules a continuation. This keeps transactions small and gives the system a durable place to resume.

Cron workload groups

The schedule covers these product needs:

  • Recovery: wake stalled account deletions and Company Monitoring purges. Reconcile missed renewals and Enterprise seat changes.
  • Customer state: scan plan-limit usage. Send due dunning, cancellation, win-back, and feedback messages.
  • Retention: remove old feedback, usage, notice, intelligence, bounce, checkout, and broadcast rows.
  • Data readiness: seed and repair shared locks used by followed-country counters and other summaries.
  • Campaign control: check the previous broadcast wave before starting the next one. Advance only when the prior wave passes its operator-defined gate.

References: convex/crons.ts• L6-75 convex/crons.ts• L84-124 convex/crons.ts• L133-182 convex/crons.ts• L184-270

Continuations and leases

Continuation work carries a cursor, generation, or expected state. A lease prevents two workers from owning the same unit. A stale continuation becomes a no-op when a newer state has already won. Reapers wake work whose continuation was lost, but they do not bypass the normal grace or retry rules.

This pattern supports renewal checks, plan-limit scans, Company Monitoring work, broadcast waves, retention, feedback delivery, and account deletion. It turns provider timeouts and Convex limits into retryable states rather than partial business results.

References: convex/crons.ts• L26-60 convex/…/billing.ts• L83-115 convex/…/admission.ts• L355-412 convex/agentFeedback.ts• L740-775 convex/schema.ts• L545-642

Account deletion workflow

Account deletion starts with a durable record and write fence. The worker removes personal rows, removes grants, anonymizes billing evidence, handles verified email-keyed rows, and runs external cleanup. Each pass has a bounded write budget, a cursor, and a bounded retry ladder.

The registry gives every schema table and relevant external record an explicit decision: delete, anonymize, retain, delegate, or skip. Late billing events remain attached to the deletion record and can resume unfinished external cleanup. They never restore access or send account mail. A stalled-work reaper can re-arm a lost continuation, while a later brief sweep removes keys written by a racing digest compose.

The lifecycle is:

flowchart LR
    A[Delete request or identity event] --> B[Tombstone and write fence]
    B --> C[Bounded personal cleanup]
    C --> D[Grant removal and billing anonymization]
    D --> E[External provider cleanup]
    E --> F[Complete and delayed brief sweep]
    C -. lost continuation .-> G[Stalled-work reaper]
    G --> C
    E -. retryable provider failure .-> H[External retry ladder]
    H --> E

References: convex/…/registry.ts• L1-7 convex/…/registry.ts• L22-315 convex/…/erase.ts• L79-193 convex/…/erase.ts• L456-490 convex/…/batches.ts• L707-837 convex/…/batches.ts• L995-1088 convex/…/sideEffects.ts• L70-123 convex/…/sideEffects.ts• L283-459

Usage and notice workflow

The plan-limit scan compares active paid access with the catalog's usage dimensions. It reads the same durable meters used for enforcement when possible. A missing, stale, malformed, or partial source blocks recovery instead of looking like zero usage.

The scan stores rollups and current notices. A coarse notice identity prevents repeated alerts during a sustained burst. Enterprise contract members are excluded from self-serve limit notices because their allowances come from the contract.

References: convex/apiPlanLimitUsage.ts• L19-59 convex/apiPlanLimitUsage.ts• L469-487 convex/apiPlanLimitUsage.ts• L508-675 convex/apiPlanLimitUsage.ts• L704-851 convex/crons.ts• L12-24

Supporting libraries

Shared libraries keep the same product decision consistent across Convex functions, HTTP routes, edge caches, and external providers. The most important shared contracts are identity, catalog features, entitlement merging, alert capabilities, provider signatures, email suppression, and signed links.

Cache synchronization

Convex remains the source of truth for entitlements and routing policy. Cache actions copy a narrow view to Redis for fast edge checks. They use short lifetimes and delayed current-state reads. Cache failures affect freshness, not the committed billing transaction, and the Convex query remains the fallback.

References: convex/…/cacheActions.ts• L16-29 convex/…/cacheActions.ts• L37-81 convex/…/cacheActions.ts• L84-140 convex/…/cacheActions.ts• L194-227

Notification delivery state

Notification channels store both the destination and the state of the latest delivery attempt. A relay starts a numbered attempt and reports a result only for the same channel identity and sequence. Repeated terminal failures disable the channel and schedule a notice so the user can repair it.

Channel creation is checked against the alert capability ladder. Web Push ownership is transferred when the same browser endpoint moves to another account, which prevents one device subscription from serving two users. First-connect welcomes use a versioned queue and an atomic deduplication claim so a timeout does not lose or duplicate the event.

References: convex/schema.ts• L143-233 convex/notificationChannels.ts• L79-185 convex/notificationChannels.ts• L193-221 convex/notificationChannels.ts• L285-377 convex/notificationChannels.ts• L630-723 convex/…/notificationDelivery.ts• L3-27

Provider boundaries

The HTTP layer exposes selected functions to the edge, relays, Telegram, payment providers, and email providers. Role-specific signature checks reject unauthenticated callbacks before state work. Shared email sending applies suppression before a provider request. One-click links use signed list-specific tokens so a worker can deliver a safe link without receiving the signing secret.

Alert and feedback routes keep cross-tenant reads internal and page them. The edge passes only validated user scope and payload shape to Convex. This keeps provider credentials and broad table scans out of browser-facing function calls.

References: convex/http.ts• L94-119 convex/http.ts• L154-224 convex/http.ts• L227-243 convex/http.ts• L630-718 convex/http.ts• L1023-1087 convex/…/resendEmail.ts• L1-19 convex/…/resendEmail.ts• L87-121

Change checklist

When these files or sections are changed, remember to consider these:

  • When a schema field or validator changes, check all writers, readers, old rows, and the generated API contract. Optional fields must have a clear read default.
  • When a user-scoped table is added, update the deletion registry and the batch walker. Give global and delegated rows an explicit lifecycle decision.
  • When a plan or feature changes in convex/…/productCatalog.ts, update product mapping, entitlement merge rules, limits, checkout admission, alert capability checks, notice targets, and generated product facts.
  • When alert capabilities or scope rules change, keep the catalog, shared capability resolver, every alert writer, relay delivery filter, migration seed, and HTTP error mapping aligned.
  • When entitlement coverage changes, keep subscription events, Enterprise membership, grants, scheduled boundary checks, and cache invalidation aligned.
  • When team dashboard access changes, keep team resolution, Business seats, Enterprise membership, focus entitlement checks, and dashboard visibility aligned.
  • When Enterprise seat rules change, keep the seat cap lock, invite token, email ownership check, contract boundary jobs, and member recompute aligned.
  • When a usage source changes, keep enforcement meters, source-health checks, rollups, notice identity, and recovery behavior aligned.
  • When a scheduled workflow changes, preserve its cursor or lease fence and its reaper or continuation path.
  • When a schema-backed counter or cap changes, keep its pre-seeded serialization row, aggregate value, and repair or reseed job aligned.
  • When a notification channel changes, keep the channel validator, relay selection, delivery sequence checks, disable path, and account-deletion cleanup aligned.
  • When a broadcast wave state changes, keep ramp gating, per-contact progress, external send steps, operator recovery, and cleanup aligned.
  • When provider contracts change, keep signature checks, payload validation, idempotency records, repair state, and response status behavior aligned.
  • When billing or operator email changes, keep suppression purpose, idempotency keys, recipient rechecks, and durable send status aligned.
  • When account deletion changes, keep the closed-world registry, personal-table walker, external snapshot, late-event fence, and delayed Redis sweep aligned.

Important failure modes

TriggerConsequenceGuard
A user-scoped schema table has no deletion decisionPersonal data can survive account deletion without an owner or repair pathRegistry coverage and batch-table coverage are checked together
A stale entitlement or routing cache is written after a newer changeThe edge can show old access or use an old provider choiceDelayed cache work reads current Convex state and lifecycle changes delete warm entries
A free account writes a wide alert rule through a partial updateDelivery or plan limits can drift from the account's current capabilityThe write path checks the effective state and the relay keeps a delivery-time clamp
A realtime alert migration runs twice after a user clears scopeThe system can undo an intentional user choiceOne marker row is created per visited rule and later runs skip it
Two first-time watchlist changes create or update counters without a shared lockA user cap or public country count can drift under concurrent writesPre-seeded user-shard and country locks serialize the mutation before the aggregate write
A notification result names an old channel or delivery sequenceA late result can clear a new failure or disable a replacement endpointResults must match channel id, link time, and pending sequence
The same web-push endpoint remains on two accountsOne user's alert can reach another account on the shared browserLinking removes matching endpoint rows from other accounts before the upsert
Two Enterprise or Business seat changes pass the cap check togetherThe account can exceed its contract or grant seat limitEvery seat mutation reads and writes the account-specific lock
An Enterprise invite is reused, forged, or accepted by another emailA user can claim access outside the intended contractThe token binds to one member row and acceptance checks expiry, email, contract, and membership
A provider webhook is authenticated but cannot be linked to an accountPayment evidence can be lost or access can remain unresolvedThe event is classified durably as unattributed for operator repair
A renewal provider read returns a broad 404 or transient errorPaying users can lose access during a provider incidentReconciliation requires repeated evidence, uses backoff, and limits mass downgrades
A usage source returns an incomplete resultA live limit notice can be cleared as if usage were zeroThe scan marks the source blocked and refuses recovery
A scheduled continuation is lostState can remain pending or write-fencedDurable cursors, retry state, leases, and reapers restart safe work
Company Monitoring evidence changes after classification startsA stale result can be published for the wrong evidenceEvidence digests, revisions, leases, and replay fences must still match
A revoked credential remains in an edge cacheA request can pass until cache expiryLifecycle actions invalidate the matching cache entries and validators fail closed
A feedback retry or security report bypasses the durable capDuplicate rows or too many owner notices can consume the triage pathRetry identity, reporter limits, a transactional daily counter, and a digest preserve bounded intake
A billing or invite email ignores local suppressionA bounced, complained-about, or blocked recipient receives more mailAll transactional sends use the shared suppression-aware sender
A deletion continuation fails before it records its errorThe account stays fenced with no visible recovery stateSetup and batch failures record status, use bounded retries, and the stalled reaper re-arms old pending rows
Redis brief cleanup runs while a compose is still writingDeleted-account brief data can return after deletionAn erase marker blocks late writes and a delayed bounded sweep removes racing keys
A wave is marked complete before all contact rows reach a terminal stateA later retry can duplicate or omit campaign deliveryWave finalization checks durable per-contact progress and keeps failed runs recoverable

Key files

FileWhy to read it
convex/schema.tsThe durable state model, state-machine rows, delivery records, indexes, and job progress
convex/…/api.d.tsThe generated public and internal function contract
convex/http.tsThe trusted boundary between Convex, the edge, relays, and providers
convex/crons.tsThe recurring schedule for recovery, customer work, retention, and data readiness
convex/…/productCatalog.tsThe shared plan, feature, limit, alert, and provider-product vocabulary
convex/…/entitlements.tsThe read-time merge that keeps old entitlement rows compatible with current catalog rules
convex/…/entitlementFeaturesValidator.tsThe stored feature contract shared by entitlement writes and cache synchronization
convex/…/alertCapabilities.tsThe plan-aware alert ladder and account-wide country-scope checks
convex/alertRules.tsAlert rule state, effective-state validation, cross-tenant paging, and delivery settings
convex/alertScopeMigration.tsThe one-time migration from unscoped realtime rules to followed-country scope
convex/notificationChannels.tsChannel ownership, welcome events, delivery attempts, failure handling, and disable notices
convex/…/notificationDelivery.tsThe delivery result and failure contract used by channels and relays
convex/users.tsThe canonical authenticated-user record, locale and language state, and deletion-aware writes
convex/teamDashboards.tsTeam resolution, shared dashboard reads and writes, focus access, limits, and version conflicts
convex/enterpriseAccounts.tsEnterprise contracts, members, locks, pooled limits, and boundary jobs
convex/enterpriseSeats.tsThe Enterprise admin invite, acceptance, removal, and invite-email lifecycle
convex/…/businessSeats.tsAPI Business grants, seat limits, signed invites, and entitlement updates
convex/…/subscriptionHelpers.tsProvider ownership, coverage selection, entitlement recomputation, and product fallback behavior
convex/…/billing.tsRenewal repair, on-demand renewal checks, customer portal access, and payment reconciliation
convex/…/unattributedPayments.tsThe operator repair queue for authenticated payment events without an account owner
convex/…/cacheActions.tsEntitlement and routing cache synchronization and credential-cache invalidation
convex/…/resendEmail.tsThe shared suppression-aware boundary for transactional and marketing email
convex/…/registry.tsThe closed-world account-data lifecycle decision
convex/…/erase.tsDeletion admission, status views, external completion, and late-event handling
convex/…/batches.tsThe bounded, resumable deletion worker, retry ladder, and stalled-work recovery
convex/…/sideEffects.tsProvider cancellation, Redis invalidation, delayed brief cleanup, and Clerk deletion
convex/…/admission.tsEvidence-bound classification and decision fencing
convex/apiPlanLimitUsage.tsUsage-source health, limit evaluation, and notice recovery
convex/agentFeedback.tsDurable feedback intake, notification, triage, retention, and digest recovery
convex/mcpProTokens.tsMCP token issuance, validation, rotation, and revocation
convex/…/identitySigning.tsSigned identity, invite, checkout, and short-lived link boundaries