pg-boss 12.26.4 → 12.28.0

package/dist/plans.js

@@ -1,5 +1,6 @@
-import { indexKeysRaw, indexPredicateRaw, displayIndexDefinition, extractFunctionBody, normalizeFunctionBody } from "./drifter.js";
+import { indexKeysRaw, indexIncludeRaw, indexPredicateRaw, displayIndexDefinition, extractFunctionBody, normalizeFunctionBody } from "./drifter.js";
 import schemaManifest from './schema.json' with { type: 'json' };
+import { normalizeSchemaName, resolveSchemaName } from "./tools.js";
 export const PG_ERROR = {
     divisionByZero: '22012'
 };
@@ -400,6 +401,7 @@ function createTableJobCommon(schema) {
     SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyStately(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyExclusive(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyKeyStrictFifo(schema)}$cmd$, '${COMMON_JOB_TABLE}');
+    SELECT ${schema}.job_table_run($cmd$${createIndexJobPolicyKeyStrictFifoHeads(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createCheckConstraintKeyStrictFifo(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobThrottle(schema)}$cmd$, '${COMMON_JOB_TABLE}');
     SELECT ${schema}.job_table_run($cmd$${createIndexJobFetch(schema)}$cmd$, '${COMMON_JOB_TABLE}');
@@ -419,6 +421,7 @@ function createTableJobIndexes(schema, noDeferrableConstraints = false, noCoveri
     ${createIndexJobPolicyStately(schema)};
     ${createIndexJobPolicyExclusive(schema)};
     ${createIndexJobPolicyKeyStrictFifo(schema)};
+    ${createIndexJobPolicyKeyStrictFifoHeads(schema, noCoveringIndex)};
     ${createCheckConstraintKeyStrictFifo(schema)};
     ${createIndexJobThrottle(schema)};
     ${createIndexJobFetch(schema, noCoveringIndex)};
@@ -549,6 +552,7 @@ function createQueueFunction(schema, noPartitioning = false) {
         EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyExclusive(schema)}$cmd$, tablename);
       ELSIF options->>'policy' = '${QUEUE_POLICIES.key_strict_fifo}' THEN
         EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyKeyStrictFifo(schema)}$cmd$, tablename);
+        EXECUTE ${schema}.job_table_format($cmd$${createIndexJobPolicyKeyStrictFifoHeads(schema)}$cmd$, tablename);
         EXECUTE ${schema}.job_table_format($cmd$${createCheckConstraintKeyStrictFifo(schema)}$cmd$, tablename);
       END IF;
 
@@ -608,8 +612,11 @@ export function createQueue(schema, name, options, noAdvisoryLocks) {
 // channel human-recognizable in pg_stat_activity; 24 hex chars leaves ample headroom under
 // the 63-byte identifier limit. Channels are already scoped to a single database, so unlike
 // advisoryLock there is no need to mix in current_database().
+//
+// normalizeSchemaName, not resolveSchemaName: the channel is never matched against the catalog, so
+// it only has to agree across instances on the same schema. See the note on the helper.
 export function notifyChannelSql(schema) {
-    return `('pgboss_' || left(encode(sha224('${schema}'::bytea), 'hex'), 24))`;
+    return `('pgboss_' || left(encode(sha224('${normalizeSchemaName(schema)}'::bytea), 'hex'), 24))`;
 }
 // Parameter-less statement that wakes workers on a notify-enabled queue. Embedded into
 // flow batches so it commits in the same transaction as the inserts.
@@ -657,6 +664,21 @@ function createIndexJobPolicyExclusive(schema) {
 function createIndexJobPolicyKeyStrictFifo(schema) {
     return `CREATE UNIQUE INDEX job_i8 ON ${schema}.job (name, singleton_key) WHERE state IN ('${JOB_STATES.active}', '${JOB_STATES.retry}', '${JOB_STATES.failed}') AND policy = '${QUEUE_POLICIES.key_strict_fifo}'`;
 }
+function createIndexJobPolicyKeyStrictFifoHeads(schema, noCoveringIndex = false) {
+    // Column order mirrors the strict_fifo_heads ORDER BY (state DESC puts a retry job ahead
+    // of created siblings) so the DISTINCT ON head-per-key scan stays an ordered index scan.
+    //
+    // INCLUDE (start_after) is load-bearing, not a covering-index habit: `policy` and `blocked`
+    // are satisfied by the partial predicate, so start_after is the only remaining filter in the
+    // heads CTE. Without it every index entry needs a heap fetch and the scan degrades from an
+    // Index Only Scan to an Index Scan (measured at 200k queued rows / 2,000 keys: 47ms -> 111ms,
+    // ~400k extra buffer hits). It costs no HOT updates that job_i5 doesn't already cost, since
+    // job_i5 indexes start_after too, and it only widens a partial index that key_strict_fifo
+    // rows enter. Backends without covering indexes (the CockroachDB profile) fall back to the
+    // narrow form and pay the heap fetches; they take a different fetch path anyway (noSkipLocked).
+    const include = noCoveringIndex ? '' : ' INCLUDE (start_after)';
+    return `CREATE INDEX job_i10 ON ${schema}.job (name, singleton_key, state DESC, created_on, id)${include} WHERE state < '${JOB_STATES.active}' AND NOT blocked AND policy = '${QUEUE_POLICIES.key_strict_fifo}'`;
+}
 function createCheckConstraintKeyStrictFifo(schema) {
     return `ALTER TABLE ${schema}.job ADD CONSTRAINT job_key_strict_fifo_singleton_key_check CHECK (NOT (policy = '${QUEUE_POLICIES.key_strict_fifo}' AND singleton_key IS NULL))`;
 }
@@ -705,7 +727,7 @@ function trySetQueueTimestamp(schema, queues, column, seconds) {
         values: [queues]
     };
 }
-export function updateQueue(schema, { deadLetter } = {}) {
+export function updateQueue(schema) {
     return `
     WITH options as (SELECT $2::jsonb as data)
     UPDATE ${schema}.queue SET
@@ -723,9 +745,9 @@ export function updateQueue(schema, { deadLetter } = {}) {
         THEN (o.data->>'heartbeatSeconds')::int
         ELSE heartbeat_seconds END,
       notify = COALESCE((o.data->>'notify')::bool, notify),
-      ${deadLetter === undefined
-        ? ''
-        : `dead_letter = CASE WHEN '${deadLetter}' IS DISTINCT FROM dead_letter THEN '${deadLetter}' ELSE dead_letter END,`}
+      dead_letter = CASE WHEN jsonb_exists(o.data, 'deadLetter')
+        THEN o.data->>'deadLetter'
+        ELSE dead_letter END,
       updated_on = now()
     FROM options o
     WHERE name = $1
@@ -918,7 +940,7 @@ export function ensureQueueStatsPartitions(schema) {
         IF NOT EXISTS (
           SELECT 1 FROM pg_class c
           JOIN pg_namespace n ON n.oid = c.relnamespace
-          WHERE n.nspname = '${schema}' AND c.relname = part_name
+          WHERE n.nspname = '${resolveSchemaName(schema)}' AND c.relname = part_name
         ) THEN
           EXECUTE format(
             'CREATE TABLE ${schema}.%I PARTITION OF ${schema}.queue_stats FOR VALUES FROM (%L) TO (%L)',
@@ -947,7 +969,7 @@ export function dropOldQueueStatsPartitions(schema, days) {
         JOIN pg_class p ON p.oid = i.inhparent
         JOIN pg_class c ON c.oid = i.inhrelid
         JOIN pg_namespace n ON n.oid = p.relnamespace
-        WHERE n.nspname = '${schema}' AND p.relname = 'queue_stats'
+        WHERE n.nspname = '${resolveSchemaName(schema)}' AND p.relname = 'queue_stats'
       LOOP
         suffix := substring(r.relname FROM 'queue_stats_(.*)$');
         IF suffix ~ '^[0-9]{8}$' THEN
@@ -1088,8 +1110,23 @@ export function setVersion(schema, version) {
 export function versionTableExists(schema) {
     return `SELECT to_regclass('${schema}.version') as name`;
 }
+// Installed pg-boss schemas whose name differs from the configured one by case alone. Postgres
+// folds a bare name and stores a quoted one verbatim, so `MySchema` and `"MySchema"` are two
+// schemas that look nearly identical in config. Used on the install path to tell a caller who
+// mis-spelled the quoting that their data is next door, rather than silently installing a second,
+// empty schema beside the populated one.
+export function getSchemaCaseVariants(schema) {
+    const resolved = resolveSchemaName(schema).replace(SINGLE_QUOTE_REGEX, "''");
+    return `
+    SELECT n.nspname as name
+    FROM pg_namespace n
+    JOIN pg_class c ON c.relnamespace = n.oid AND c.relname = 'version' AND c.relkind IN ('r', 'p')
+    WHERE lower(n.nspname) = lower('${resolved}') AND n.nspname <> '${resolved}'
+    ORDER BY n.nspname
+  `;
+}
 export function getPartitionedQueueTables(schema) {
-    return `SELECT table_name FROM ${schema}.queue WHERE partition = true`;
+    return `SELECT table_name, policy FROM ${schema}.queue WHERE partition = true`;
 }
 export function insertVersion(schema, version) {
     return `INSERT INTO ${schema}.version(version) VALUES ('${version}')`;
@@ -1168,6 +1205,7 @@ function buildFetchParams(options) {
  */
 export function fetchNextJob(options, noSkipLocked = false) {
     const { schema, table, name, policy, limit, includeMetadata, priority = true, orderByCreatedOn = true, ignoreStartAfter = false, groupConcurrency, minPriority, maxPriority } = options;
+    const keyStrictFifo = policy === QUEUE_POLICIES.key_strict_fifo;
     const singletonFetch = limit > 1 && (policy === QUEUE_POLICIES.singleton || policy === QUEUE_POLICIES.stately);
     const hasIgnoreSingletons = options.ignoreSingletons != null && options.ignoreSingletons.length > 0;
     const hasIgnoreGroups = options.ignoreGroups != null && options.ignoreGroups.length > 0;
@@ -1228,6 +1266,23 @@ export function fetchNextJob(options, noSkipLocked = false) {
             : `(j.group_id IS NULL
             OR ${activeGroupCountExpression} < ${groupLimit})`
         : '';
+    // state DESC (retry > created in the enum) makes a retry job its key's head. job_i8
+    // guarantees at most one job per key in active/retry/failed, and the NOT EXISTS blocker
+    // below rejects every sibling of a retry job — so if created_on picked the head, an older
+    // deferred job whose start_after has since arrived would claim the head slot while being
+    // unfetchable, and the retry job (fetchable but not the head) would deadlock the key.
+    const strictFifoHeadsCte = keyStrictFifo
+        ? `strict_fifo_heads AS MATERIALIZED (
+        SELECT DISTINCT ON (h.singleton_key) h.id
+        FROM ${schema}.${table} h
+        WHERE h.name = '${name}'
+          AND h.state < '${JOB_STATES.active}'
+          AND NOT h.blocked
+          AND h.policy = '${QUEUE_POLICIES.key_strict_fifo}'
+          ${!ignoreStartAfter ? 'AND h.start_after <= now()' : ''}
+        ORDER BY h.singleton_key, h.state DESC, h.created_on, h.id
+      ), `
+        : '';
     const whereConditions = [
         `j.name = '${name}'`,
         `j.state < '${JOB_STATES.active}'`,
@@ -1238,6 +1293,18 @@ export function fetchNextJob(options, noSkipLocked = false) {
         // timestamp, so `<` would leave freshly-inserted jobs invisible until the clock ticks.
         // NOTIFY gating already uses `start_after <= now()` for the same reason.
         !ignoreStartAfter ? 'j.start_after <= now()' : '',
+        keyStrictFifo ? 'j.id IN (SELECT id FROM strict_fifo_heads)' : '',
+        keyStrictFifo
+            ? `NOT EXISTS (
+            SELECT 1
+            FROM ${schema}.${table} b
+            WHERE b.name = j.name
+              AND b.singleton_key = j.singleton_key
+              AND b.state IN ('${JOB_STATES.active}', '${JOB_STATES.retry}', '${JOB_STATES.failed}')
+              AND b.policy = '${QUEUE_POLICIES.key_strict_fifo}'
+              AND b.id <> j.id
+          )`
+            : '',
         hasIgnoreSingletons ? `COALESCE(j.singleton_key, '') <> ALL(${params.ignoreSingletonsParam})` : '',
         hasIgnoreGroups ? `(j.group_id IS NULL OR j.group_id <> ALL(${params.ignoreGroupsParam}))` : '',
         hasMinPriority ? `j.priority >= ${params.minPriorityParam}` : '',
@@ -1296,6 +1363,7 @@ export function fetchNextJob(options, noSkipLocked = false) {
     return {
         text: `
       WITH
+      ${strictFifoHeadsCte}
       ${activeGroupCountMapCte}
       ${nextCte}
       ${singletonCte}
@@ -1443,6 +1511,26 @@ export function restoreJobs(schema, table) {
       AND id = ANY($2::uuid[])
   `;
 }
+// A `startAfter` string is either an absolute date time or a delay expressed as a Postgres
+// interval. A trailing 'Z' has always marked a date time; a leading ISO 8601 calendar date
+// (YYYY-MM-DD) marks one as well, which is what lets the other 8601 zone designators through
+// ('+00:00', '+05:30', '-08:00') along with zone-less and date-only strings — all of which
+// used to reach the interval cast and fail as 'invalid input syntax for type interval'.
+//
+// Recognition is only ever widened, so anything that resolves as an interval today still
+// does: bare seconds ('0', '300'), phrases ('5 minutes'), ISO 8601 durations ('PT1H') and
+// the year-month form ('2027-01', which Postgres reads as 2027 years 1 mon) carry neither
+// mark. A date time with an explicit offset resolves to that exact instant.
+//
+// A zone-less date time would otherwise be cast in the database session's TimeZone, so the
+// public entry points pin it to UTC before it gets here (Attorney.pinZonelessDateTime). This
+// cast is still session-TZ dependent for anything that reaches it unpinned, which is why the
+// pin lives at the boundary rather than in this expression: a caller may legitimately pass a
+// form Postgres resolves itself ('2027-01-01 08:00:00 America/New_York'), and rewriting those
+// in SQL would mean re-implementing timestamp parsing in a regex.
+function isDateTimeString(expression) {
+    return `(right(${expression}, 1) = 'Z' OR ${expression} ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}')`;
+}
 export function insertJobs(schema, { table, name, returnId = true, notify = false }) {
     // When notify is enabled we always RETURN start_after so the wrapper below can gate
     // the NOTIFY on immediate availability, regardless of whether the caller wants ids.
@@ -1501,7 +1589,7 @@ export function insertJobs(schema, { table, name, returnId = true, notify = fals
     FROM (
       SELECT *,
         CASE
-          WHEN right("startAfter", 1) = 'Z' THEN CAST("startAfter" as timestamp with time zone)
+          WHEN ${isDateTimeString('"startAfter"')} THEN CAST("startAfter" as timestamp with time zone)
           ELSE now() + CAST(COALESCE("startAfter",'0') as interval)
           END as start_after
       FROM json_to_recordset($1::json) as x (
@@ -1775,10 +1863,11 @@ function failJobsBody(schema, table, where, output, forceTerminal = false) {
       SELECT * FROM failed_jobs
     ),
     dlq_jobs as (
-      INSERT INTO ${schema}.job (name, data, output, retry_limit, retry_backoff, retry_delay, keep_until, deletion_seconds,
-        expire_seconds, source_name, source_id, source_created_on, source_retry_count, singleton_key, heartbeat_seconds)
+      INSERT INTO ${schema}.job (name, priority, data, output, retry_limit, retry_backoff, retry_delay, keep_until, deletion_seconds,
+        expire_seconds, source_name, source_id, source_created_on, source_retry_count, singleton_key, group_id, group_tier, heartbeat_seconds)
       SELECT
         r.dead_letter,
+        r.priority,
         r.data,
         r.output,
         q.retry_limit,
@@ -1792,7 +1881,9 @@ function failJobsBody(schema, table, where, output, forceTerminal = false) {
         r.created_on,
         r.retry_count,
         r.singleton_key,
-        r.heartbeat_seconds
+        r.group_id,
+        r.group_tier,
+        q.heartbeat_seconds
       FROM results r
         JOIN ${schema}.queue q ON q.name = r.dead_letter
       WHERE state = '${JOB_STATES.failed}'
@@ -1987,9 +2078,10 @@ export function insertRetryJob(schema, table) {
 export function insertDeadLetterJob(schema) {
     return `
     INSERT INTO ${schema}.job (name, data, output, retry_limit, retry_backoff, retry_delay, keep_until, deletion_seconds,
-      expire_seconds, source_name, source_id, source_created_on, source_retry_count, singleton_key, heartbeat_seconds)
+      expire_seconds, source_name, source_id, source_created_on, source_retry_count, singleton_key, heartbeat_seconds,
+      priority, group_id, group_tier)
     SELECT $1, $2, $3, q.retry_limit, q.retry_backoff, q.retry_delay, now() + q.retention_seconds * interval '1s', q.deletion_seconds,
-      q.expire_seconds, $4, $5, $6, $7, $8, $9
+      q.expire_seconds, $4, $5, $6, $7, $8, q.heartbeat_seconds, $9, $10, $11
     FROM ${schema}.queue q WHERE q.name = $1
   `;
 }
@@ -1998,7 +2090,11 @@ export function insertDeadLetterJob(schema) {
 // oldest-first, capped at $4. The JOIN in `candidates` only matches jobs whose destination queue
 // exists, so legacy/orphaned jobs (NULL source_name, no override) are never deleted — they stay
 // in the DLQ rather than being lost. Re-created jobs get a new id, `created` state, retry_count 0,
-// cleared output, NULL source_*, and the destination queue's current retry/retention/policy config.
+// cleared output, NULL source_*, and every queue-config column (retry/retention/policy/expiry/
+// heartbeat/dead_letter) from the destination queue as it is configured now — per-job overrides
+// from the original send() are not preserved, since the DLQ copy never stored them. `dead_letter`
+// is the same value send() falls back to, so a second terminal failure re-enters the DLQ.
+// Job-identity columns (priority, singleton_key, group_id, group_tier) are carried over instead.
 export function redriveJobs(schema, table) {
     return `
     WITH candidates AS (
@@ -2020,11 +2116,12 @@ export function redriveJobs(schema, table) {
     ins AS (
       INSERT INTO ${schema}.job
         (name, data, priority, retry_limit, retry_backoff, retry_delay, retry_delay_max,
-         expire_seconds, keep_until, deletion_seconds, policy, singleton_key, heartbeat_seconds)
+         expire_seconds, keep_until, deletion_seconds, policy, singleton_key, group_id, group_tier,
+         heartbeat_seconds, dead_letter)
       SELECT COALESCE($2, m.source_name), m.data, m.priority, q.retry_limit, q.retry_backoff,
         q.retry_delay, q.retry_delay_max, q.expire_seconds,
         now() + q.retention_seconds * interval '1s', q.deletion_seconds, q.policy,
-        m.singleton_key, m.heartbeat_seconds
+        m.singleton_key, m.group_id, m.group_tier, q.heartbeat_seconds, q.dead_letter
       FROM moved m JOIN ${schema}.queue q ON q.name = COALESCE($2, m.source_name)
       -- A destination queue's short/stately policy can still collide on (name, singleton_key)
       -- if two redriven jobs share a key (job_i1/job_i3); dropping just that row here, matching
@@ -2080,11 +2177,11 @@ export function updateJob(schema, table, name, by, match, notify = false) {
     const ordering = (by === 'singletonKey' && match !== 'all')
         ? `ORDER BY job.created_on ${match === 'oldest' ? 'ASC' : 'DESC'} LIMIT 1`
         : '';
-    // Resolve the incoming startAfter the same way insertJobs does (absolute 'Z' timestamp vs.
+    // Resolve the incoming startAfter the same way insertJobs does (absolute date time vs.
     // relative interval), falling back to the row's current start_after when not supplied.
     const resolvedStartAfter = `
         CASE WHEN jsonb_exists(o.data, 'startAfter')
-          THEN CASE WHEN right(o.data->>'startAfter', 1) = 'Z'
+          THEN CASE WHEN ${isDateTimeString("o.data->>'startAfter'")}
                  THEN (o.data->>'startAfter')::timestamptz
                  ELSE now() + CAST(o.data->>'startAfter' AS interval) END
           ELSE job.start_after END`;
@@ -2278,9 +2375,12 @@ export function locked(schema, query, key, noAdvisoryLocks) {
     const statements = Array.isArray(query) ? query : [query];
     return transaction(noAdvisoryLocks ? statements : [advisoryLock(schema, key), ...statements]);
 }
+// normalizeSchemaName, not resolveSchemaName: the key is opaque to postgres and never compared
+// against the catalog, so it only has to agree across instances on the same schema. See the note
+// on the helper.
 function advisoryLock(schema, key) {
     return `SELECT pg_advisory_xact_lock(
-      ('x' || encode(sha224((current_database() || '.pgboss.${schema}${key || ''}')::bytea), 'hex'))::bit(64)::bigint
+      ('x' || encode(sha224((current_database() || '.pgboss.${normalizeSchemaName(schema)}${key || ''}')::bytea), 'hex'))::bit(64)::bigint
   )`;
 }
 export function assertMigration(schema, version) {
@@ -2437,7 +2537,7 @@ export function getNextBamCommand(schema, { useLiveness = false } = {}) {
       AND l.granted
       AND l.mode = 'ShareUpdateExclusiveLock'
       AND l.database = (SELECT oid FROM pg_database WHERE datname = current_database())
-      AND l.relation = to_regclass(quote_ident('${schema}') || '.' || quote_ident(${tableCol}))
+      AND l.relation = to_regclass(quote_ident('${resolveSchemaName(schema)}') || '.' || quote_ident(${tableCol}))
   )`;
     const stale = (startedCol, tableCol) => `(
     ${startedCol} < now() - interval '${BAM_LIVENESS_GRACE_SECONDS} seconds'
@@ -2510,7 +2610,7 @@ export function bamHealProbe(schema, command) {
     FROM pg_class c
     JOIN pg_index i ON i.indexrelid = c.oid
     JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = '${schema.replace(SINGLE_QUOTE_REGEX, "''")}' AND c.relname = '${match[1].replace(SINGLE_QUOTE_REGEX, "''")}'
+    WHERE n.nspname = '${resolveSchemaName(schema).replace(SINGLE_QUOTE_REGEX, "''")}' AND c.relname = '${match[1].replace(SINGLE_QUOTE_REGEX, "''")}'
   `;
 }
 export function setBamCompleted(schema, id) {
@@ -2577,7 +2677,8 @@ const POLICY_JOB_INDEXES = {
     2: QUEUE_POLICIES.singleton,
     3: QUEUE_POLICIES.stately,
     6: QUEUE_POLICIES.exclusive,
-    8: QUEUE_POLICIES.key_strict_fifo
+    8: QUEUE_POLICIES.key_strict_fifo,
+    10: QUEUE_POLICIES.key_strict_fifo
 };
 // job_iN indexes with no policy gate — created on every job table regardless of policy
 // (throttle i4, fetch i5, group-concurrency i7, blocking i9).
@@ -2677,7 +2778,7 @@ export function expectedManagedFunctions(schema, partitioned) {
 export function expectedManagedIndexes(schema, partitioned, partitions = []) {
     const managed = (name, table, indexdef) => {
         const def = applyManifestSchema(indexdef, schema);
-        return { name, table, keys: indexKeysRaw(def), predicate: indexPredicateRaw(def), definition: displayIndexDefinition(def) };
+        return { name, table, keys: indexKeysRaw(def), include: indexIncludeRaw(def), predicate: indexPredicateRaw(def), definition: displayIndexDefinition(def) };
     };
     const jobTable = partitioned ? COMMON_JOB_TABLE : 'job';
     const out = [];

package/dist/schema.json

@@ -1,6 +1,6 @@
 {
     "_generated": "Generated by scripts/gen-manifest.ts — do not edit by hand. Run `npm run gen:manifest`.",
-    "version": 37,
+    "version": 38,
     "schemaToken": "{{schema}}",
     "partitioned": {
         "tables": [
@@ -1060,6 +1060,12 @@
                 "valid": true,
                 "def": "CREATE UNIQUE INDEX job_common_i1 ON {{schema}}.job_common USING btree (name, COALESCE(singleton_key, ''::text)) WHERE ((state = 'created'::{{schema}}.job_state) AND (policy = 'short'::text))"
             },
+            {
+                "name": "job_common_i10",
+                "table": "job_common",
+                "valid": true,
+                "def": "CREATE INDEX job_common_i10 ON {{schema}}.job_common USING btree (name, singleton_key, state DESC, created_on, id) INCLUDE (start_after) WHERE ((state < 'active'::{{schema}}.job_state) AND (NOT blocked) AND (policy = 'key_strict_fifo'::text))"
+            },
             {
                 "name": "job_common_i2",
                 "table": "job_common",
@@ -1130,7 +1136,7 @@
         "functions": [
             {
                 "name": "create_queue",
-                "def": "CREATE OR REPLACE FUNCTION {{schema}}.create_queue(queue_name text, options jsonb)\n RETURNS void\n LANGUAGE plpgsql\nAS $function$\n    DECLARE\n      tablename varchar := CASE WHEN options->>'partition' = 'true'\n                            THEN 'j' || encode(sha224(queue_name::bytea), 'hex')\n                            ELSE 'job_common'\n                            END;\n      queue_created_on timestamptz;\n    BEGIN\n\n      WITH q as (\n        INSERT INTO {{schema}}.queue (\n          name,\n          policy,\n          retry_limit,\n          retry_delay,\n          retry_backoff,\n          retry_delay_max,\n          expire_seconds,\n          retention_seconds,\n          deletion_seconds,\n          warning_queued,\n          dead_letter,\n          partition,\n          table_name,\n          heartbeat_seconds,\n          notify\n        )\n        VALUES (\n          queue_name,\n          options->>'policy',\n          COALESCE((options->>'retryLimit')::int, 2),\n          COALESCE((options->>'retryDelay')::int, 0),\n          COALESCE((options->>'retryBackoff')::bool, false),\n          (options->>'retryDelayMax')::int,\n          COALESCE((options->>'expireInSeconds')::int, 900),\n          COALESCE((options->>'retentionSeconds')::int, 1209600),\n          COALESCE((options->>'deleteAfterSeconds')::int, 604800),\n          COALESCE((options->>'warningQueueSize')::int, 0),\n          options->>'deadLetter',\n          COALESCE((options->>'partition')::bool, false),\n          tablename,\n          (options->>'heartbeatSeconds')::int,\n          COALESCE((options->>'notify')::bool, false)\n        )\n        ON CONFLICT DO NOTHING\n        RETURNING created_on\n      )\n      SELECT created_on into queue_created_on from q;\n\n      IF queue_created_on IS NULL OR options->>'partition' IS DISTINCT FROM 'true' THEN\n        RETURN;\n      END IF;\n\n      EXECUTE format('CREATE TABLE {{schema}}.%I (LIKE {{schema}}.job INCLUDING DEFAULTS)', tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD PRIMARY KEY (name, id)$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT q_fkey FOREIGN KEY (name) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT dlq_fkey FOREIGN KEY (dead_letter) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i5 ON {{schema}}.job (name, start_after) WHERE state < 'active' AND NOT blocked$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i4 ON {{schema}}.job (name, singleton_on, COALESCE(singleton_key, '')) WHERE state <> 'cancelled' AND singleton_on IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i7 ON {{schema}}.job (name, group_id) WHERE state = 'active' AND group_id IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i9 ON {{schema}}.job (name, id) WHERE blocking AND state = 'completed'$cmd$, tablename);\n\n      IF options->>'policy' = 'short' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i1 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'created' AND policy = 'short'$cmd$, tablename);\n      ELSIF options->>'policy' = 'singleton' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i2 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'active' AND policy = 'singleton'$cmd$, tablename);\n      ELSIF options->>'policy' = 'stately' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i3 ON {{schema}}.job (name, state, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'stately'$cmd$, tablename);\n      ELSIF options->>'policy' = 'exclusive' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i6 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'exclusive'$cmd$, tablename);\n      ELSIF options->>'policy' = 'key_strict_fifo' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i8 ON {{schema}}.job (name, singleton_key) WHERE state IN ('active', 'retry', 'failed') AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT job_key_strict_fifo_singleton_key_check CHECK (NOT (policy = 'key_strict_fifo' AND singleton_key IS NULL))$cmd$, tablename);\n      END IF;\n\n      EXECUTE format('ALTER TABLE {{schema}}.%I ADD CONSTRAINT cjc CHECK (name=%L)', tablename, queue_name);\n      EXECUTE format('ALTER TABLE {{schema}}.job ATTACH PARTITION {{schema}}.%I FOR VALUES IN (%L)', tablename, queue_name);\n    END;\n    $function$\n"
+                "def": "CREATE OR REPLACE FUNCTION {{schema}}.create_queue(queue_name text, options jsonb)\n RETURNS void\n LANGUAGE plpgsql\nAS $function$\n    DECLARE\n      tablename varchar := CASE WHEN options->>'partition' = 'true'\n                            THEN 'j' || encode(sha224(queue_name::bytea), 'hex')\n                            ELSE 'job_common'\n                            END;\n      queue_created_on timestamptz;\n    BEGIN\n\n      WITH q as (\n        INSERT INTO {{schema}}.queue (\n          name,\n          policy,\n          retry_limit,\n          retry_delay,\n          retry_backoff,\n          retry_delay_max,\n          expire_seconds,\n          retention_seconds,\n          deletion_seconds,\n          warning_queued,\n          dead_letter,\n          partition,\n          table_name,\n          heartbeat_seconds,\n          notify\n        )\n        VALUES (\n          queue_name,\n          options->>'policy',\n          COALESCE((options->>'retryLimit')::int, 2),\n          COALESCE((options->>'retryDelay')::int, 0),\n          COALESCE((options->>'retryBackoff')::bool, false),\n          (options->>'retryDelayMax')::int,\n          COALESCE((options->>'expireInSeconds')::int, 900),\n          COALESCE((options->>'retentionSeconds')::int, 1209600),\n          COALESCE((options->>'deleteAfterSeconds')::int, 604800),\n          COALESCE((options->>'warningQueueSize')::int, 0),\n          options->>'deadLetter',\n          COALESCE((options->>'partition')::bool, false),\n          tablename,\n          (options->>'heartbeatSeconds')::int,\n          COALESCE((options->>'notify')::bool, false)\n        )\n        ON CONFLICT DO NOTHING\n        RETURNING created_on\n      )\n      SELECT created_on into queue_created_on from q;\n\n      IF queue_created_on IS NULL OR options->>'partition' IS DISTINCT FROM 'true' THEN\n        RETURN;\n      END IF;\n\n      EXECUTE format('CREATE TABLE {{schema}}.%I (LIKE {{schema}}.job INCLUDING DEFAULTS)', tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD PRIMARY KEY (name, id)$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT q_fkey FOREIGN KEY (name) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT dlq_fkey FOREIGN KEY (dead_letter) REFERENCES {{schema}}.queue (name) ON DELETE RESTRICT DEFERRABLE INITIALLY DEFERRED$cmd$, tablename);\n\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i5 ON {{schema}}.job (name, start_after) WHERE state < 'active' AND NOT blocked$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i4 ON {{schema}}.job (name, singleton_on, COALESCE(singleton_key, '')) WHERE state <> 'cancelled' AND singleton_on IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i7 ON {{schema}}.job (name, group_id) WHERE state = 'active' AND group_id IS NOT NULL$cmd$, tablename);\n      EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i9 ON {{schema}}.job (name, id) WHERE blocking AND state = 'completed'$cmd$, tablename);\n\n      IF options->>'policy' = 'short' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i1 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'created' AND policy = 'short'$cmd$, tablename);\n      ELSIF options->>'policy' = 'singleton' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i2 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state = 'active' AND policy = 'singleton'$cmd$, tablename);\n      ELSIF options->>'policy' = 'stately' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i3 ON {{schema}}.job (name, state, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'stately'$cmd$, tablename);\n      ELSIF options->>'policy' = 'exclusive' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i6 ON {{schema}}.job (name, COALESCE(singleton_key, '')) WHERE state <= 'active' AND policy = 'exclusive'$cmd$, tablename);\n      ELSIF options->>'policy' = 'key_strict_fifo' THEN\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE UNIQUE INDEX job_i8 ON {{schema}}.job (name, singleton_key) WHERE state IN ('active', 'retry', 'failed') AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$CREATE INDEX job_i10 ON {{schema}}.job (name, singleton_key, state DESC, created_on, id) INCLUDE (start_after) WHERE state < 'active' AND NOT blocked AND policy = 'key_strict_fifo'$cmd$, tablename);\n        EXECUTE {{schema}}.job_table_format($cmd$ALTER TABLE {{schema}}.job ADD CONSTRAINT job_key_strict_fifo_singleton_key_check CHECK (NOT (policy = 'key_strict_fifo' AND singleton_key IS NULL))$cmd$, tablename);\n      END IF;\n\n      EXECUTE format('ALTER TABLE {{schema}}.%I ADD CONSTRAINT cjc CHECK (name=%L)', tablename, queue_name);\n      EXECUTE format('ALTER TABLE {{schema}}.job ATTACH PARTITION {{schema}}.%I FOR VALUES IN (%L)', tablename, queue_name);\n    END;\n    $function$\n"
             },
             {
                 "name": "delete_queue",
@@ -1986,6 +1992,12 @@
                 "valid": true,
                 "def": "CREATE UNIQUE INDEX job_i1 ON {{schema}}.job USING btree (name, COALESCE(singleton_key, ''::text)) WHERE ((state = 'created'::{{schema}}.job_state) AND (policy = 'short'::text))"
             },
+            {
+                "name": "job_i10",
+                "table": "job",
+                "valid": true,
+                "def": "CREATE INDEX job_i10 ON {{schema}}.job USING btree (name, singleton_key, state DESC, created_on, id) INCLUDE (start_after) WHERE ((state < 'active'::{{schema}}.job_state) AND (NOT blocked) AND (policy = 'key_strict_fifo'::text))"
+            },
             {
                 "name": "job_i2",
                 "table": "job",

package/dist/timekeeper.d.ts

@@ -13,6 +13,7 @@ declare class Timekeeper extends EventEmitter implements types.EventsMixin {
     private skewMonitorInterval;
     private timekeeping;
     private _checkingSkew;
+    private warnedSchedules;
     clockSkew: number;
     events: {
         error: string;

package/dist/timekeeper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timekeeper.d.ts","sourceRoot":"","sources":["../src/timekeeper.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAGnC,eAAO,MAAM,MAAM;;CAElB,CAAA;AAkBD,cAAM,UAAW,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;IAChE,EAAE,EAAE,KAAK,CAAC,SAAS,CAAA;IACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B,CAAA;IACxC,OAAO,EAAE,OAAO,CAAA;IAEhB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,aAAa,CAAQ;IAE7B,SAAS,SAAI;IACb,MAAM;;;;MAAS;gBAEF,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAQ5F,IAAI,YAAY,IAAK,OAAO,CAE3B;IAED,OAAO,KAAK,cAAc,GASzB;IAEK,KAAK;IAmBL,IAAI;IAwBJ,cAAc;IAyCd,MAAM;IA0BN,IAAI;IAYV,YAAY,CAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;YAYxB,QAAQ;IAWhB,YAAY,CAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAiBrE,QAAQ,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,KAAK,CAAC,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzG,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"timekeeper.d.ts","sourceRoot":"","sources":["../src/timekeeper.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAGnC,eAAO,MAAM,MAAM;;CAElB,CAAA;AAwCD,cAAM,UAAW,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;IAChE,EAAE,EAAE,KAAK,CAAC,SAAS,CAAA;IACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B,CAAA;IACxC,OAAO,EAAE,OAAO,CAAA;IAEhB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,aAAa,CAAQ;IAS7B,OAAO,CAAC,eAAe,CAAoB;IAE3C,SAAS,SAAI;IACb,MAAM;;;;MAAS;gBAEF,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAQ5F,IAAI,YAAY,IAAK,OAAO,CAE3B;IAED,OAAO,KAAK,cAAc,GASzB;IAEK,KAAK;IAqBL,IAAI;IAwBJ,cAAc;IAyCd,MAAM;IA0BN,IAAI;IA8CV,YAAY,CAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;YAYxB,QAAQ;IAWhB,YAAY,CAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAiBrE,QAAQ,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,KAAK,CAAC,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBzG,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD;AAED,eAAe,UAAU,CAAA"}

package/dist/timekeeper.js

@@ -19,8 +19,30 @@ const WARNINGS = {
     }
 };
 const WARNING_TYPES = {
-    CLOCK_SKEW: 'clock_skew'
+    CLOCK_SKEW: 'clock_skew',
+    INVALID_SCHEDULE: 'invalid_schedule'
 };
+/**
+ * Asserts that `tz` is a time zone cron evaluation can actually use.
+ *
+ * cron-parser validates `tz` lazily: parsing without a reference date never constructs a CronDate,
+ * so every string is accepted and a bad zone only surfaces later, when a date is computed, as an
+ * opaque "CronDate: unhandled timestamp". Passing a reference date here forces that construction so
+ * a typo like 'America/New_Yrok' is rejected by schedule() rather than persisted to the schedule
+ * table. Deliberately reuses cron-parser rather than an independent Intl check, so what schedule()
+ * accepts is exactly what the cron pass can evaluate.
+ *
+ * The caller validates the cron expression first, so a failure here is attributable to the zone.
+ */
+function assertTimezone(tz) {
+    try {
+        CronExpressionParser.parse('* * * * *', { tz, strict: false, currentDate: new Date() });
+    }
+    catch {
+        // Quoted so an empty string renders as `""` rather than a dangling colon
+        throw new Error(`Unknown or unsupported time zone: "${tz}"`);
+    }
+}
 class Timekeeper extends EventEmitter {
     db;
     config;
@@ -30,6 +52,14 @@ class Timekeeper extends EventEmitter {
     skewMonitorInterval;
     timekeeping;
     _checkingSkew = false;
+    // Rows already warned about, keyed on (name, key, cron, timezone). Unlike every other warning
+    // type, an unusable schedule never heals on its own: clock skew converges, a backlog drains, a
+    // slow query is a one-off, but a bad row sits there until a human edits it. Warning every pass
+    // would persist a row every cronMonitorIntervalSeconds forever, and warningRetentionDays has no
+    // default, so a single typo could grow the warning table without bound. Rebuilt each pass from
+    // the rows still broken, so a fixed or deleted schedule drops out and would warn again if it
+    // came back.
+    warnedSchedules = new Set();
     clockSkew = 0;
     events = EVENTS;
     constructor(db, manager, config) {
@@ -53,6 +83,8 @@ class Timekeeper extends EventEmitter {
     }
     async start() {
         this.stopped = false;
+        // A restart should re-surface a row nobody has fixed yet
+        this.warnedSchedules.clear();
         await this.cacheClockSkew();
         await this.manager.createQueue(QUEUES.SEND_IT);
         const options = {
@@ -134,9 +166,32 @@ class Timekeeper extends EventEmitter {
     }
     async cron() {
         const schedules = await this.getSchedules();
-        const scheduled = schedules
-            .filter(i => this.shouldSendIt(i.cron, i.timezone))
-            .map(({ name, key, data, options }) => ({ data: { name, data, options }, singletonKey: `${name}__${key}`, singletonSeconds: 60 }));
+        const scheduled = [];
+        const stillBroken = new Set();
+        for (const { name, key, data, options, cron, timezone } of schedules) {
+            let due;
+            try {
+                due = this.shouldSendIt(cron, timezone);
+            }
+            catch (err) {
+                // Evaluating one row must not decide the fate of the others. schedule() now rejects an
+                // unusable time zone, but a row written by an earlier release — or straight into the table —
+                // still throws here. This was a single filter() over every schedule, so one such row
+                // propagated out of cron() and silently stopped scheduling for every queue in the
+                // deployment, on every pass, until someone found the row. Skip it and warn instead, naming
+                // the schedule so it is actually fixable.
+                const warned = JSON.stringify([name, key, cron, timezone]);
+                stillBroken.add(warned);
+                if (!this.warnedSchedules.has(warned)) {
+                    await emitAndPersistWarning(this.warningContext, WARNING_TYPES.INVALID_SCHEDULE, `Warning: schedule for queue "${name}" (key "${key}") could not be evaluated and was skipped: ${err.message}`, { queue: name, key, cron, timezone });
+                }
+                continue;
+            }
+            if (due) {
+                scheduled.push({ data: { name, data, options }, singletonKey: `${name}__${key}`, singletonSeconds: 60 });
+            }
+        }
+        this.warnedSchedules = stillBroken;
         if (scheduled.length > 0 && !this.stopped) {
             await this.manager.insert(QUEUES.SEND_IT, scheduled);
         }
@@ -173,7 +228,12 @@ class Timekeeper extends EventEmitter {
     }
     async schedule(name, cron, data, options = {}) {
         const { tz = 'UTC', key = '', ...rest } = options;
-        CronExpressionParser.parse(cron, { tz, strict: false });
+        // Expression first, so a bad expression reports as one rather than as a time zone problem. The
+        // check is deliberately run against UTC rather than the supplied tz: it only works today
+        // because cron-parser is lazy about an unusable zone, and if that ever changes this call would
+        // throw the opaque "CronDate: unhandled timestamp" that assertTimezone exists to replace.
+        CronExpressionParser.parse(cron, { tz: 'UTC', strict: false });
+        assertTimezone(tz);
         Attorney.checkSendArgs([name, data, { ...rest }]);
         Attorney.assertKey(key);
         try {

package/dist/tools.d.ts

@@ -18,5 +18,36 @@ export interface AbortablePromise<T> extends Promise<T> {
 }
 declare function delay(ms: number, error?: string, abortController?: AbortController): AbortablePromise<void>;
 declare function resolveWithinSeconds<T>(promise: Promise<T>, seconds: number, message?: string, abortController?: AbortController): Promise<T | void>;
-export { delay, resolveWithinSeconds, unwrapSQLResult };
+/**
+ * Resolves a configured schema string to the name postgres actually stores in the catalog.
+ *
+ * the `schema` option is interpolated verbatim into identifier positions, so a caller may quote it
+ * to reach names that are not legal bare identifiers, e.g. `'"My-Schema"'`. The catalog holds the
+ * *resolved* name, so any comparison against `pg_namespace.nspname` (and anything else reading a
+ * name back out of postgres) needs this rather than the raw config value.
+ *
+ * A quoted name resolves to its contents verbatim; a bare one is folded to lower case, as postgres
+ * does on the way in. So `"MySchema"` and `MySchema` are different schemas, the latter stored as
+ * `myschema`.
+ *
+ * Do NOT use this to derive the notify channel or the advisory lock - see normalizeSchemaName.
+ */
+declare function resolveSchemaName(schema: string): string;
+/**
+ * Canonicalizes a configured schema string for the values pg-boss *derives* from it rather than
+ * looks up: the notify channel name and the advisory lock key.
+ *
+ * Those are hashes of a string, never compared against the catalog - the channel literal is
+ * generated from the same expression for both LISTEN and NOTIFY, and the advisory key is opaque to
+ * postgres. So the only requirement is that every instance pointed at the same physical schema
+ * agrees, which means the *sole* transform needed is collapsing quoting that carries no meaning:
+ * `'"pgboss"'` and `'pgboss'` are one schema and must not end up on separate channels.
+ *
+ * Deliberately NOT resolveSchemaName. Folding a bare `MySchema` to `myschema` would also be
+ * "correct", but it changes the channel and lock key for a name that has always been legal, so a
+ * rolling upgrade would leave old and new instances failing to coordinate. Leaving bare names
+ * untouched keeps the derived values byte-identical to every prior release.
+ */
+declare function normalizeSchemaName(schema: string): string;
+export { delay, normalizeSchemaName, resolveSchemaName, resolveWithinSeconds, unwrapSQLResult };
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA;;;;;;;EAOE;AACF,iBAAS,eAAe,CAAE,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,EAAE,GAAG,GAAG,EAAE,GAAG;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAQ9F;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACrD,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,iBAAS,KAAK,CAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAsBrG;AAED,iBAAe,oBAAoB,CAAC,CAAC,EAAG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAapJ;AAED,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,eAAe,EAChB,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA;;;;;;;EAOE;AACF,iBAAS,eAAe,CAAE,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,EAAE,GAAG,GAAG,EAAE,GAAG;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAQ9F;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACrD,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,iBAAS,KAAK,CAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAsBrG;AAED,iBAAe,oBAAoB,CAAC,CAAC,EAAG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAapJ;AAQD;;;;;;;;;;;;;GAaG;AACH,iBAAS,iBAAiB,CAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;;;GAcG;AACH,iBAAS,mBAAmB,CAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,OAAO,EACL,KAAK,EACL,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EAChB,CAAA"}

package/dist/tools.js

@@ -48,4 +48,43 @@ async function resolveWithinSeconds(promise, seconds, message, abortController)
     }
     return result;
 }
-export { delay, resolveWithinSeconds, unwrapSQLResult };
+// a quoted name whose contents are already a legal bare identifier *and* already lower case, so
+// postgres would resolve the two spellings to the same schema.
+const REDUNDANTLY_QUOTED_SCHEMA_REGEX = /^"[a-z_][a-z0-9_]*"$/;
+const isQuoted = (schema) => schema.startsWith('"') && schema.endsWith('"') && schema.length > 1;
+/**
+ * Resolves a configured schema string to the name postgres actually stores in the catalog.
+ *
+ * the `schema` option is interpolated verbatim into identifier positions, so a caller may quote it
+ * to reach names that are not legal bare identifiers, e.g. `'"My-Schema"'`. The catalog holds the
+ * *resolved* name, so any comparison against `pg_namespace.nspname` (and anything else reading a
+ * name back out of postgres) needs this rather than the raw config value.
+ *
+ * A quoted name resolves to its contents verbatim; a bare one is folded to lower case, as postgres
+ * does on the way in. So `"MySchema"` and `MySchema` are different schemas, the latter stored as
+ * `myschema`.
+ *
+ * Do NOT use this to derive the notify channel or the advisory lock - see normalizeSchemaName.
+ */
+function resolveSchemaName(schema) {
+    return isQuoted(schema) ? schema.slice(1, -1) : schema.toLowerCase();
+}
+/**
+ * Canonicalizes a configured schema string for the values pg-boss *derives* from it rather than
+ * looks up: the notify channel name and the advisory lock key.
+ *
+ * Those are hashes of a string, never compared against the catalog - the channel literal is
+ * generated from the same expression for both LISTEN and NOTIFY, and the advisory key is opaque to
+ * postgres. So the only requirement is that every instance pointed at the same physical schema
+ * agrees, which means the *sole* transform needed is collapsing quoting that carries no meaning:
+ * `'"pgboss"'` and `'pgboss'` are one schema and must not end up on separate channels.
+ *
+ * Deliberately NOT resolveSchemaName. Folding a bare `MySchema` to `myschema` would also be
+ * "correct", but it changes the channel and lock key for a name that has always been legal, so a
+ * rolling upgrade would leave old and new instances failing to coordinate. Leaving bare names
+ * untouched keeps the derived values byte-identical to every prior release.
+ */
+function normalizeSchemaName(schema) {
+    return REDUNDANTLY_QUOTED_SCHEMA_REGEX.test(schema) ? schema.slice(1, -1) : schema;
+}
+export { delay, normalizeSchemaName, resolveSchemaName, resolveWithinSeconds, unwrapSQLResult };