Improve task staleness detection and fix serialization group isolation

[Tosd0]

Summary

This PR enhances the scheduled message delivery system with better staleness detection for retrying tasks and fixes a critical bug in serialization group isolation. It also refactors shared Postgres query logic and improves error handling across multiple handlers.

Key Changes

Core Delivery Logic (run-tick.js)

• Configurable staleness threshold: Added ctx.staleAfterMs parameter to allow hosts to override the default STALE_AFTER_MS (1 hour). Tasks on retry chains are now considered stale if their retry_after timestamp has also been exceeded by this threshold, indicating the outage occurred during the retry window.
• Improved retry failure handling: Added errorCode parameter to handleDeliveryFailure() to distinguish permanent failures (PUSH_SUBSCRIPTION_MISSING, PUSH_SUBSCRIPTION_STORE_UNSUPPORTED) from transient ones. Permanent failures skip the retry backoff ladder entirely.
• Reduced code duplication: Consolidated nearly identical recurring/non-recurring task expiration logic into a single code path using a plan object pattern.
• Fixed serialization group isolation bug: Group serialization keys now include user_id to prevent different users' tasks with the same group name from blocking each other. Added post-commit verification to catch write skew conflicts in READ COMMITTED isolation.

Shared Postgres Implementation (pg-shared.js)

• Extracted common Postgres query logic (claimTask, getPushSubscription, upsertPushSubscription, deletePushSubscription) into a new shared module used by both pg.js and neon.js adapters. This ensures SQL and concurrency semantics remain identical across Postgres deployments.
• Documented write skew handling for grouped task claims with detailed comments.

Request Handling (request.js)

• Added requireUserId() utility function to centralize X-User-Id validation (required + UUID v4 format) across all user-scoped endpoints, eliminating duplicated validation logic.
• Added errorResponse() helper for consistent error envelope formatting.

Message Processing (message-processor.js)

• Added predecrypted parameter to processSingleMessage() to allow callers (run-tick's pre-scan) to pass already-decrypted payloads, avoiding redundant decryption.
• Updated return type to include optional errorCode field for error classification.

Push Subscription Handling (push-subscription-store.js)

• Enhanced resolvePushSubscription() with legacyFallback parameter to support subscriptions embedded in older task payloads while preferring user-level stored subscriptions.
• Added codedError() helper to attach stable error codes for branch-based error handling instead of message matching.

Handler Consolidation

• schedule-message.js, update-message.js, get-user-key.js, get-message.js, messages.js, cancel-message.js, client-state.js, push-subscription.js: Replaced inline X-User-Id validation with requireUserId() call.

Infrastructure & Utilities

• blob-store.js: Unified base64url encoding/decoding with shared implementation from webcrypto-utils.js to ensure consistency across token and blob storage.
• context.js: Improved adapter initialization to cache promises (not just adapters) and automatically run initSchema() on first adapter creation per process, with proper error handling and cache cleanup on failure.
• single-user-worker.js: Added error handling for cors.origin callback failures and config resolution failures in scheduled handler to prevent uncaught exceptions.
• validation.js: Re-exported isValidUrl from shared package to maintain consistent URL validation across packages.
• schema.js: Centralized UPDATABLE_COLUMNS whitelist for all three adapters (pg, neon, d1) to ensure consistency when adding new columns.

Testing

• Updated pg-neon-adapter.test.mjs to verify write skew recovery: after a grouped task claim succeeds, a follow-up query checks for conflicts and releases the lease if another task in

https://claude.ai/code/session_01QL5HkjoCMcdij3jtBPYJP9