gorsee 0.2.10 → 0.2.12

package/dist-pkg/server/manifest.js

@@ -1,15 +1,24 @@
 import { join } from "node:path";
 import { readFile } from "node:fs/promises";
-export const BUILD_MANIFEST_SCHEMA_VERSION = 1;
+export const BUILD_MANIFEST_SCHEMA_VERSION = 1, RELEASE_ARTIFACT_SCHEMA_VERSION = 1;
 export async function loadBuildManifest(distDir) {
   const raw = await readFile(join(distDir, "manifest.json"), "utf-8");
   return parseBuildManifest(raw);
 }
+export async function loadReleaseArtifact(distDir) {
+  const raw = await readFile(join(distDir, "release.json"), "utf-8");
+  return parseReleaseArtifact(raw);
+}
 export function parseBuildManifest(raw) {
   const manifest = JSON.parse(raw);
   validateBuildManifest(manifest);
   return manifest;
 }
+export function parseReleaseArtifact(raw) {
+  const artifact = JSON.parse(raw);
+  validateReleaseArtifact(artifact);
+  return artifact;
+}
 function validateBuildManifest(manifest) {
   if (manifest.schemaVersion !== BUILD_MANIFEST_SCHEMA_VERSION)
     throw Error(`Unsupported build manifest schema version: expected ${BUILD_MANIFEST_SCHEMA_VERSION}, received ${String(manifest.schemaVersion)}`);
@@ -22,6 +31,26 @@ function validateBuildManifest(manifest) {
   if (typeof manifest.buildTime !== "string" || manifest.buildTime.length === 0)
     throw Error("Invalid build manifest: buildTime must be a non-empty string");
 }
+function validateReleaseArtifact(artifact) {
+  if (artifact.schemaVersion !== RELEASE_ARTIFACT_SCHEMA_VERSION)
+    throw Error(`Unsupported release artifact schema version: expected ${RELEASE_ARTIFACT_SCHEMA_VERSION}, received ${String(artifact.schemaVersion)}`);
+  if (artifact.appMode !== "frontend" && artifact.appMode !== "fullstack" && artifact.appMode !== "server")
+    throw Error("Invalid release artifact: appMode must be frontend, fullstack, or server");
+  if (typeof artifact.generatedAt !== "string" || artifact.generatedAt.length === 0)
+    throw Error("Invalid release artifact: generatedAt must be a non-empty string");
+  if (!artifact.summary || typeof artifact.summary !== "object")
+    throw Error("Invalid release artifact: summary must be an object");
+  if (!artifact.runtime || typeof artifact.runtime !== "object")
+    throw Error("Invalid release artifact: runtime must be an object");
+  if (!artifact.artifacts || typeof artifact.artifacts !== "object")
+    throw Error("Invalid release artifact: artifacts must be an object");
+  if (!Array.isArray(artifact.artifacts.clientAssets) || !Array.isArray(artifact.artifacts.serverEntries) || !Array.isArray(artifact.artifacts.prerenderedHtml))
+    throw Error("Invalid release artifact: artifact file groups must be arrays");
+  if (typeof artifact.artifacts.buildManifest !== "string" || artifact.artifacts.buildManifest.length === 0)
+    throw Error("Invalid release artifact: buildManifest must be a non-empty string");
+  if (!Array.isArray(artifact.runtime.processEntrypoints) || !Array.isArray(artifact.runtime.handlerEntrypoints))
+    throw Error("Invalid release artifact: runtime entrypoint groups must be arrays");
+}
 export function getRouteBuildEntry(manifest, pathname) {
   return manifest.routes[pathname];
 }

package/dist-pkg/server/redis-client.d.ts

@@ -9,6 +9,9 @@ export interface RedisLikeClient {
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
     setnx?(key: string, value: string): Awaitable<number>;
+    zadd?(key: string, score: number, member: string): Awaitable<number>;
+    zrangebyscore?(key: string, min: number | "-inf", max: number | "+inf"): Awaitable<string[]>;
+    zrem?(key: string, ...members: string[]): Awaitable<number>;
 }
 export declare function buildRedisKey(prefix: string, key: string): string;
 export declare function stripRedisPrefix(prefix: string, key: string): string;
@@ -22,6 +25,9 @@ export interface NodeRedisClientLike {
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
     setnx?(key: string, value: string): Awaitable<number>;
+    zadd?(key: string, score: number, member: string): Awaitable<number>;
+    zrangebyscore?(key: string, min: number | "-inf", max: number | "+inf"): Awaitable<string[]>;
+    zrem?(key: string, ...members: string[]): Awaitable<number>;
 }
 export interface IORedisClientLike {
     get(key: string): Awaitable<string | null>;
@@ -33,6 +39,9 @@ export interface IORedisClientLike {
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
     setnx?(key: string, value: string): Awaitable<number>;
+    zadd?(key: string, score: number, member: string): Awaitable<number>;
+    zrangebyscore?(key: string, min: number | "-inf", max: number | "+inf"): Awaitable<string[]>;
+    zrem?(key: string, ...members: string[]): Awaitable<number>;
 }
 export declare function createNodeRedisLikeClient(client: NodeRedisClientLike): RedisLikeClient;
 export declare function createIORedisLikeClient(client: IORedisClientLike): RedisLikeClient;

package/dist-pkg/server/redis-client.js

@@ -15,7 +15,10 @@ export function createNodeRedisLikeClient(client) {
     expire: client.expire ? (key, seconds) => client.expire(key, seconds) : void 0,
     pttl: client.pttl ? (key) => client.pttl(key) : void 0,
     ttl: client.ttl ? (key) => client.ttl(key) : void 0,
-    setnx: client.setnx ? (key, value) => client.setnx(key, value) : void 0
+    setnx: client.setnx ? (key, value) => client.setnx(key, value) : void 0,
+    zadd: client.zadd ? (key, score, member) => client.zadd(key, score, member) : void 0,
+    zrangebyscore: client.zrangebyscore ? (key, min, max) => client.zrangebyscore(key, min, max) : void 0,
+    zrem: client.zrem ? (key, ...members) => client.zrem(key, ...members) : void 0
   };
 }
 export function createIORedisLikeClient(client) {

package/dist-pkg/server/redis-job-queue.d.ts

@@ -3,6 +3,8 @@ import { type RedisLikeClient } from "./redis-client.js";
 interface RedisJobQueueOptions {
     prefix?: string;
     lockTtlSeconds?: number;
+    lockRenewIntervalMs?: number;
+    historyLimit?: number;
     jobs?: Array<JobDefinition<unknown>>;
     instanceId?: string;
 }

package/dist-pkg/server/redis-job-queue.js

@@ -1,26 +1,41 @@
+import { emitJobLifecycleEvent } from "./jobs.js";
 import { buildRedisKey, stripRedisPrefix } from "./redis-client.js";
 export function createRedisJobQueue(client, options = {}) {
   if (!client.incr || !client.expire || !client.setnx)
     throw Error("Redis job queue requires incr(), expire(), and setnx() support on the Redis client.");
-  const prefix = options.prefix ?? "gorsee:jobs", lockTtlSeconds = options.lockTtlSeconds ?? 30, instanceId = options.instanceId ?? crypto.randomUUID(), handlers = new Map;
+  const prefix = options.prefix ?? "gorsee:jobs", lockTtlSeconds = options.lockTtlSeconds ?? 30, lockRenewIntervalMs = options.lockRenewIntervalMs ?? Math.max(1000, Math.floor(lockTtlSeconds * 1000 / 3)), historyLimit = options.historyLimit ?? 100, instanceId = options.instanceId ?? crypto.randomUUID(), handlers = new Map;
   for (const job of options.jobs ?? [])
     handlers.set(job.name, job);
   return {
     async enqueue(job, payload, enqueueOptions = {}) {
       handlers.set(job.name, job);
-      const sequence = await client.incr(buildRedisKey(prefix, "__sequence")), id = `${job.name}:${sequence}:${crypto.randomUUID()}`, enqueued = {
+      const sequence = await client.incr(buildRedisKey(prefix, "__sequence")), id = `${job.name}:${sequence}:${crypto.randomUUID()}`, runAt = enqueueOptions.runAt ?? Date.now(), enqueued = {
         id,
         name: job.name,
         payload,
-        runAt: enqueueOptions.runAt ?? Date.now(),
+        runAt,
         attempts: 0,
         maxAttempts: enqueueOptions.maxAttempts ?? 3,
         backoffMs: enqueueOptions.backoffMs ?? 1000
-      };
-      await client.set(jobKey(prefix, id), JSON.stringify({
+      }, stored = {
         ...enqueued,
-        sequence
-      }));
+        sequence,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        scheduleMember: buildScheduleMember(sequence, id)
+      };
+      await writeStoredJob(client, prefix, stored);
+      await emitJobLifecycleEvent({
+        kind: "job.enqueue",
+        severity: "info",
+        queue: "redis",
+        id: stored.id,
+        name: stored.name,
+        attempts: stored.attempts,
+        maxAttempts: stored.maxAttempts,
+        runAt: stored.runAt,
+        workerInstanceId: instanceId
+      });
       return enqueued;
     },
     async runNext(now = Date.now()) {
@@ -30,13 +45,45 @@ export function createRedisJobQueue(client, options = {}) {
         if (await client.setnx(lockKey, instanceId) !== 1)
           continue;
         await client.expire(lockKey, lockTtlSeconds);
+        const renewTimer = startLockRenewal(client, lockKey, lockTtlSeconds, lockRenewIntervalMs);
         try {
           const current = await readStoredJob(client, prefix, job.id);
           if (!current || current.runAt > now)
             continue;
+          await emitJobLifecycleEvent({
+            kind: "job.start",
+            severity: "info",
+            queue: "redis",
+            id: current.id,
+            name: current.name,
+            attempts: current.attempts + 1,
+            maxAttempts: current.maxAttempts,
+            runAt: current.runAt,
+            workerInstanceId: instanceId
+          });
           const handler = handlers.get(current.name);
           if (!handler) {
-            await client.del(jobKey(prefix, current.id));
+            await archiveTerminalJob(client, prefix, historyLimit, {
+              ...current,
+              attempts: current.attempts + 1,
+              lastError: `Missing Redis job handler registration for "${current.name}"`,
+              finishedAt: Date.now(),
+              status: "failed",
+              historyMember: buildHistoryMember(current.sequence, current.id)
+            });
+            await deleteStoredJob(client, prefix, current);
+            await emitJobLifecycleEvent({
+              kind: "job.fail",
+              severity: "error",
+              queue: "redis",
+              id: current.id,
+              name: current.name,
+              attempts: current.attempts + 1,
+              maxAttempts: current.maxAttempts,
+              runAt: current.runAt,
+              workerInstanceId: instanceId,
+              error: `Missing Redis job handler registration for "${current.name}"`
+            });
             return {
               id: current.id,
               name: current.name,
@@ -51,7 +98,25 @@ export function createRedisJobQueue(client, options = {}) {
               attempt: current.attempts,
               maxAttempts: current.maxAttempts
             });
-            await client.del(jobKey(prefix, current.id));
+            current.updatedAt = Date.now();
+            await archiveTerminalJob(client, prefix, historyLimit, {
+              ...current,
+              finishedAt: Date.now(),
+              status: "completed",
+              historyMember: buildHistoryMember(current.sequence, current.id)
+            });
+            await deleteStoredJob(client, prefix, current);
+            await emitJobLifecycleEvent({
+              kind: "job.complete",
+              severity: "info",
+              queue: "redis",
+              id: current.id,
+              name: current.name,
+              attempts: current.attempts,
+              maxAttempts: current.maxAttempts,
+              runAt: current.runAt,
+              workerInstanceId: instanceId
+            });
             return {
               id: current.id,
               name: current.name,
@@ -63,7 +128,21 @@ export function createRedisJobQueue(client, options = {}) {
             if (current.attempts < current.maxAttempts) {
               current.lastError = message;
               current.runAt = now + current.backoffMs * current.attempts;
-              await client.set(jobKey(prefix, current.id), JSON.stringify(current));
+              current.updatedAt = Date.now();
+              await writeStoredJob(client, prefix, current);
+              await emitJobLifecycleEvent({
+                kind: "job.retry",
+                severity: "warn",
+                queue: "redis",
+                id: current.id,
+                name: current.name,
+                attempts: current.attempts,
+                maxAttempts: current.maxAttempts,
+                runAt: now,
+                nextRunAt: current.runAt,
+                workerInstanceId: instanceId,
+                error: message
+              });
               return {
                 id: current.id,
                 name: current.name,
@@ -73,7 +152,27 @@ export function createRedisJobQueue(client, options = {}) {
                 error: message
               };
             }
-            await client.del(jobKey(prefix, current.id));
+            current.lastError = message;
+            current.updatedAt = Date.now();
+            await archiveTerminalJob(client, prefix, historyLimit, {
+              ...current,
+              finishedAt: Date.now(),
+              status: "failed",
+              historyMember: buildHistoryMember(current.sequence, current.id)
+            });
+            await deleteStoredJob(client, prefix, current);
+            await emitJobLifecycleEvent({
+              kind: "job.fail",
+              severity: "error",
+              queue: "redis",
+              id: current.id,
+              name: current.name,
+              attempts: current.attempts,
+              maxAttempts: current.maxAttempts,
+              runAt: current.runAt,
+              workerInstanceId: instanceId,
+              error: message
+            });
             return {
               id: current.id,
               name: current.name,
@@ -83,6 +182,7 @@ export function createRedisJobQueue(client, options = {}) {
             };
           }
         } finally {
+          clearLockRenewal(renewTimer);
           await client.del(lockKey);
         }
       }
@@ -99,6 +199,66 @@ export function createRedisJobQueue(client, options = {}) {
     },
     async size() {
       return (await listStoredJobs(client, prefix)).length;
+    },
+    async get(id) {
+      const job = await readStoredJob(client, prefix, id);
+      if (!job)
+        return null;
+      return toQueuedJobRecord(job);
+    },
+    async peek(limit = Number.POSITIVE_INFINITY) {
+      return (await listStoredJobs(client, prefix)).sort((a, b) => a.runAt - b.runAt || a.sequence - b.sequence).slice(0, limit).map((job) => toQueuedJobRecord(job));
+    },
+    async cancel(id) {
+      const job = await readStoredJob(client, prefix, id);
+      if (!job)
+        return !1;
+      if (await client.get(claimKey(prefix, id)))
+        return !1;
+      await deleteStoredJob(client, prefix, job);
+      await emitJobLifecycleEvent({
+        kind: "job.cancel",
+        severity: "info",
+        queue: "redis",
+        id: job.id,
+        name: job.name,
+        attempts: job.attempts,
+        maxAttempts: job.maxAttempts,
+        runAt: job.runAt,
+        workerInstanceId: instanceId
+      });
+      return !0;
+    },
+    async recent(limit = 50) {
+      return (await listTerminalJobs(client, prefix, limit)).map(toTerminalJobRecord);
+    },
+    async failures(limit = 50) {
+      return (await listFailedTerminalJobs(client, prefix, limit)).map(toTerminalJobRecord);
+    },
+    async retryFailed(id, options = {}) {
+      const failed = await readStoredTerminalJob(client, prefix, id);
+      if (!failed || failed.status !== "failed")
+        return null;
+      const handler = handlers.get(failed.name);
+      if (!handler)
+        return null;
+      const retried = await this.enqueue(handler, failed.payload, {
+        runAt: options.runAt ?? Date.now(),
+        maxAttempts: options.maxAttempts ?? failed.maxAttempts,
+        backoffMs: options.backoffMs ?? failed.backoffMs
+      });
+      await emitJobLifecycleEvent({
+        kind: "job.dead-letter.retry",
+        severity: "warn",
+        queue: "redis",
+        id: retried.id,
+        name: retried.name,
+        attempts: retried.attempts,
+        maxAttempts: retried.maxAttempts,
+        runAt: retried.runAt,
+        workerInstanceId: instanceId
+      });
+      return retried;
     }
   };
 }
@@ -108,7 +268,32 @@ function jobKey(prefix, id) {
 function claimKey(prefix, id) {
   return buildRedisKey(`${prefix}:lock`, id);
 }
+function scheduleKey(prefix) {
+  return buildRedisKey(prefix, "__schedule");
+}
+function historyIndexKey(prefix) {
+  return buildRedisKey(prefix, "__history");
+}
+function failedIndexKey(prefix) {
+  return buildRedisKey(prefix, "__failed");
+}
+function historyItemKey(prefix, id) {
+  return buildRedisKey(`${prefix}:history`, id);
+}
 async function listStoredJobs(client, prefix) {
+  if (client.zrangebyscore) {
+    const members = await client.zrangebyscore(scheduleKey(prefix), "-inf", "+inf"), jobs = [];
+    for (const member of members) {
+      const job = await readStoredJob(client, prefix, extractJobIdFromScheduleMember(member));
+      if (job) {
+        jobs.push(job);
+        continue;
+      }
+      if (client.zrem)
+        await client.zrem(scheduleKey(prefix), member);
+    }
+    return jobs;
+  }
   const keys = await client.keys(`${prefix}:*`), jobs = [];
   for (const key of keys) {
     const visibleKey = stripRedisPrefix(prefix, key);
@@ -121,6 +306,19 @@ async function listStoredJobs(client, prefix) {
   return jobs;
 }
 async function listDueJobs(client, prefix, now) {
+  if (client.zrangebyscore) {
+    const members = await client.zrangebyscore(scheduleKey(prefix), "-inf", now), jobs = [];
+    for (const member of members) {
+      const job = await readStoredJob(client, prefix, extractJobIdFromScheduleMember(member));
+      if (job) {
+        jobs.push(job);
+        continue;
+      }
+      if (client.zrem)
+        await client.zrem(scheduleKey(prefix), member);
+    }
+    return jobs;
+  }
   return (await listStoredJobs(client, prefix)).filter((job) => job.runAt <= now).sort((a, b) => a.runAt - b.runAt || a.sequence - b.sequence);
 }
 async function readStoredJob(client, prefix, id) {
@@ -128,14 +326,234 @@ async function readStoredJob(client, prefix, id) {
   if (!raw)
     return null;
   try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed.id !== "string" || typeof parsed.name !== "string") {
-      await client.del(jobKey(prefix, id));
+    const parsed = JSON.parse(raw), normalized = normalizeStoredJob(parsed, id);
+    if (!normalized) {
+      await deleteCorruptStoredJob(client, prefix, id);
+      return null;
+    }
+    if (!isStoredJob(parsed))
+      await writeStoredJob(client, prefix, normalized);
+    return normalized;
+  } catch {
+    await deleteCorruptStoredJob(client, prefix, id);
+    return null;
+  }
+}
+async function writeStoredJob(client, prefix, job) {
+  await client.set(jobKey(prefix, job.id), JSON.stringify(job));
+  if (client.zadd)
+    await client.zadd(scheduleKey(prefix), job.runAt, job.scheduleMember);
+}
+async function deleteStoredJob(client, prefix, job) {
+  await client.del(jobKey(prefix, job.id));
+  if (client.zrem)
+    await client.zrem(scheduleKey(prefix), job.scheduleMember);
+}
+async function deleteCorruptStoredJob(client, prefix, id) {
+  await client.del(jobKey(prefix, id));
+  if (client.zrem)
+    await client.zrem(scheduleKey(prefix), ...candidateScheduleMembersForCorruptJob(id));
+}
+async function archiveTerminalJob(client, prefix, historyLimit, job) {
+  await client.set(historyItemKey(prefix, job.id), JSON.stringify(job));
+  if (client.zadd) {
+    await client.zadd(historyIndexKey(prefix), job.finishedAt, job.historyMember);
+    if (job.status === "failed")
+      await client.zadd(failedIndexKey(prefix), job.finishedAt, job.historyMember);
+    else if (client.zrem)
+      await client.zrem(failedIndexKey(prefix), job.historyMember);
+    await trimTerminalHistory(client, prefix, historyLimit);
+  }
+}
+async function trimTerminalHistory(client, prefix, historyLimit) {
+  if (!client.zrangebyscore || !client.zrem || historyLimit < 0)
+    return;
+  const history = await client.zrangebyscore(historyIndexKey(prefix), "-inf", "+inf"), overflow = history.length - historyLimit;
+  if (overflow <= 0)
+    return;
+  const toDelete = history.slice(0, overflow);
+  for (const member of toDelete) {
+    const id = extractJobIdFromHistoryMember(member);
+    await client.del(historyItemKey(prefix, id));
+    await client.zrem(historyIndexKey(prefix), member);
+    await client.zrem(failedIndexKey(prefix), member);
+  }
+}
+async function listTerminalJobs(client, prefix, limit) {
+  return listIndexedTerminalJobs(client, prefix, historyIndexKey(prefix), limit);
+}
+async function listFailedTerminalJobs(client, prefix, limit) {
+  return listIndexedTerminalJobs(client, prefix, failedIndexKey(prefix), limit);
+}
+async function listIndexedTerminalJobs(client, prefix, indexKey, limit) {
+  if (!client.zrangebyscore)
+    return [];
+  const members = await client.zrangebyscore(indexKey, "-inf", "+inf"), records = [];
+  for (const member of members.slice(-limit).reverse()) {
+    const record = await readStoredTerminalJob(client, prefix, extractJobIdFromHistoryMember(member));
+    if (record) {
+      records.push(record);
+      continue;
+    }
+    if (client.zrem)
+      await client.zrem(indexKey, member);
+  }
+  return records;
+}
+async function readStoredTerminalJob(client, prefix, id) {
+  const raw = await client.get(historyItemKey(prefix, id));
+  if (!raw)
+    return null;
+  try {
+    const parsed = JSON.parse(raw), normalized = normalizeStoredTerminalJob(parsed, id);
+    if (!normalized) {
+      await client.del(historyItemKey(prefix, id));
       return null;
     }
-    return parsed;
+    return normalized;
   } catch {
-    await client.del(jobKey(prefix, id));
+    await client.del(historyItemKey(prefix, id));
     return null;
   }
 }
+function buildScheduleMember(sequence, id) {
+  return `${String(sequence).padStart(12, "0")}:${id}`;
+}
+function buildHistoryMember(sequence, id) {
+  return `${String(sequence).padStart(12, "0")}:${id}`;
+}
+function extractJobIdFromScheduleMember(member) {
+  const delimiterIndex = member.indexOf(":");
+  return delimiterIndex === -1 ? member : member.slice(delimiterIndex + 1);
+}
+function extractJobIdFromHistoryMember(member) {
+  const delimiterIndex = member.indexOf(":");
+  return delimiterIndex === -1 ? member : member.slice(delimiterIndex + 1);
+}
+function candidateScheduleMembersForCorruptJob(id) {
+  return [
+    id,
+    `000000000000:${id}`
+  ];
+}
+function isStoredJob(value) {
+  if (!value || typeof value !== "object")
+    return !1;
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.name === "string" && typeof candidate.runAt === "number" && typeof candidate.attempts === "number" && typeof candidate.maxAttempts === "number" && typeof candidate.backoffMs === "number" && typeof candidate.sequence === "number" && typeof candidate.createdAt === "number" && typeof candidate.updatedAt === "number" && typeof candidate.scheduleMember === "string";
+}
+function toQueuedJobRecord(job) {
+  return {
+    id: job.id,
+    name: job.name,
+    payload: job.payload,
+    runAt: job.runAt,
+    attempts: job.attempts,
+    maxAttempts: job.maxAttempts,
+    backoffMs: job.backoffMs,
+    lastError: job.lastError,
+    createdAt: job.createdAt,
+    updatedAt: job.updatedAt
+  };
+}
+function toTerminalJobRecord(job) {
+  return {
+    id: job.id,
+    name: job.name,
+    payload: job.payload,
+    runAt: job.runAt,
+    attempts: job.attempts,
+    maxAttempts: job.maxAttempts,
+    backoffMs: job.backoffMs,
+    lastError: job.lastError,
+    createdAt: job.createdAt,
+    updatedAt: job.updatedAt,
+    finishedAt: job.finishedAt,
+    status: job.status
+  };
+}
+function normalizeStoredJob(value, id) {
+  if (typeof value.id !== "string" || value.id !== id)
+    return null;
+  if (typeof value.name !== "string")
+    return null;
+  if (typeof value.runAt !== "number")
+    return null;
+  if (typeof value.attempts !== "number")
+    return null;
+  if (typeof value.maxAttempts !== "number")
+    return null;
+  if (typeof value.backoffMs !== "number")
+    return null;
+  if (typeof value.sequence !== "number")
+    return null;
+  const createdAt = typeof value.createdAt === "number" ? value.createdAt : value.runAt, updatedAt = typeof value.updatedAt === "number" ? value.updatedAt : createdAt, scheduleMember = typeof value.scheduleMember === "string" ? value.scheduleMember : buildScheduleMember(value.sequence, value.id);
+  return {
+    id: value.id,
+    name: value.name,
+    payload: value.payload,
+    runAt: value.runAt,
+    attempts: value.attempts,
+    maxAttempts: value.maxAttempts,
+    backoffMs: value.backoffMs,
+    lastError: value.lastError,
+    sequence: value.sequence,
+    createdAt,
+    updatedAt,
+    scheduleMember
+  };
+}
+function normalizeStoredTerminalJob(value, id) {
+  if (typeof value.id !== "string" || value.id !== id)
+    return null;
+  if (typeof value.name !== "string")
+    return null;
+  if (typeof value.runAt !== "number")
+    return null;
+  if (typeof value.attempts !== "number")
+    return null;
+  if (typeof value.maxAttempts !== "number")
+    return null;
+  if (typeof value.backoffMs !== "number")
+    return null;
+  if (typeof value.sequence !== "number")
+    return null;
+  if (typeof value.createdAt !== "number")
+    return null;
+  if (typeof value.updatedAt !== "number")
+    return null;
+  if (typeof value.finishedAt !== "number")
+    return null;
+  if (value.status !== "completed" && value.status !== "failed")
+    return null;
+  return {
+    id: value.id,
+    name: value.name,
+    payload: value.payload,
+    runAt: value.runAt,
+    attempts: value.attempts,
+    maxAttempts: value.maxAttempts,
+    backoffMs: value.backoffMs,
+    lastError: value.lastError,
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+    finishedAt: value.finishedAt,
+    status: value.status,
+    sequence: value.sequence,
+    historyMember: typeof value.historyMember === "string" ? value.historyMember : buildHistoryMember(value.sequence, value.id)
+  };
+}
+function startLockRenewal(client, lockKey, lockTtlSeconds, renewIntervalMs) {
+  if (renewIntervalMs <= 0)
+    return null;
+  const timer = setInterval(() => {
+    client.expire?.(lockKey, lockTtlSeconds);
+  }, renewIntervalMs);
+  if (typeof timer.unref === "function")
+    timer.unref();
+  return timer;
+}
+function clearLockRenewal(timer) {
+  if (timer)
+    clearInterval(timer);
+}

package/dist-pkg/server/worker-service.d.ts

@@ -0,0 +1,33 @@
+type Awaitable<T> = T | Promise<T>;
+export interface WorkerServiceContext {
+    name: string;
+    workerId: string;
+    startedAt: number;
+    signal: AbortSignal;
+    emitReady(): Promise<void>;
+    emitHeartbeat(message?: string, data?: Record<string, unknown>): Promise<void>;
+    waitForShutdown(): Promise<void>;
+}
+export interface WorkerServiceStartHandle {
+    ready?: Promise<void>;
+    stop?: () => Awaitable<void>;
+}
+export interface WorkerServiceDefinition {
+    name: string;
+    start(context: WorkerServiceContext): Awaitable<void | (() => Awaitable<void>) | WorkerServiceStartHandle>;
+}
+export interface RunWorkerServiceOptions {
+    registerSignalHandlers?: boolean;
+    workerId?: string;
+    signal?: AbortSignal;
+}
+export interface RunningWorkerService {
+    name: string;
+    workerId: string;
+    startedAt: number;
+    ready: Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function defineWorkerService(name: string, start: WorkerServiceDefinition["start"]): WorkerServiceDefinition;
+export declare function runWorkerService(service: WorkerServiceDefinition, options?: RunWorkerServiceOptions): Promise<RunningWorkerService>;
+export {};