gorsee 0.2.9 → 0.2.11

package/README.md

@@ -175,6 +175,7 @@ Capabilities are not bolt-on features. They are part of the framework contract:
 - auth and session stores
 - request policy and security validation
 - route cache with explicit intent
+- single-instance defaults plus explicit multi-instance runtime contracts
 - type-safe route generation
 - validated forms
 - deploy adapters with provider assumptions
@@ -219,6 +220,13 @@ const userRoute = createTypedRoute("/users/[id]")
 - Use `gorsee/compat` only for explicit legacy migration semantics.
 - `Link` prefetch is explicit: `prefetch={true}` is eager, `prefetch="hover"` is pointer/focus triggered, and `prefetch="viewport"` is IntersectionObserver-driven. Links without `prefetch` do not prefetch implicitly.
 
+## Multi-Instance Runtime
+
+- Gorsee defaults remain safe for single-node apps, but multi-instance deployments must be declared explicitly with `runtime.topology = "multi-instance"` in `app.config.ts`.
+- In multi-instance mode, production runtime fails closed unless `security.rateLimit.limiter` is configured with a distributed backend such as `createRedisRateLimiter(...)`.
+- Use `createRedisSessionStore(...)`, `createRedisCacheStore(...)`, and `createRedisJobQueue(...)` for session/cache/jobs when replicas must share state.
+- Keep `.gorsee/*` local artifacts for node-local triage, and add `ai.bridge.url` when fleet-level AI event aggregation is required.
+
 ## Package Distribution
 
 - workspace development stays Bun-first and source-first

package/bin/gorsee.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { spawnSync } from "node:child_process"
+
+const binDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(binDir, "..")
+const publishedCliEntry = join(packageRoot, "dist-pkg", "cli", "index.js")
+const sourceCliEntry = join(packageRoot, "src", "cli", "index.ts")
+
+function runWithBun(entry) {
+  const result = spawnSync("bun", ["run", entry, ...process.argv.slice(2)], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+  })
+  process.exit(result.status ?? 1)
+}
+
+function hasBun() {
+  const result = spawnSync("bun", ["--version"], {
+    cwd: packageRoot,
+    stdio: "ignore",
+  })
+  return result.status === 0
+}
+
+if (existsSync(publishedCliEntry) && hasBun()) {
+  runWithBun(publishedCliEntry)
+} else if (existsSync(sourceCliEntry) && hasBun()) {
+  runWithBun(sourceCliEntry)
+} else if (existsSync(publishedCliEntry)) {
+  await import(pathToFileURL(publishedCliEntry).href)
+} else {
+  console.error("gorsee launcher could not find a runnable CLI entrypoint.")
+  process.exit(1)
+}

package/dist-pkg/cli/check-ast.d.ts

@@ -10,7 +10,10 @@ export interface ASTFileFacts {
     issues: ASTCheckIssue[];
     hasServerCall: boolean;
     hasRouteCacheCall: boolean;
+    hasRouteCacheExplicitStore: boolean;
     hasCreateAuthCall: boolean;
+    hasCreateMemorySessionStoreCall: boolean;
+    hasCreateMemoryJobQueueCall: boolean;
     hasRedirectCall: boolean;
     hasCtxRedirectCall: boolean;
     hasLegacyLoaderExport: boolean;

package/dist-pkg/cli/check-ast.js

@@ -45,6 +45,16 @@ function hasRouteCacheIntent(ts, expr) {
     return name === "includeAuthHeaders" || name === "vary" || name === "key" || name === "mode";
   });
 }
+function hasRouteCacheStore(ts, expr) {
+  const firstArg = expr.arguments[0];
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
+    return !1;
+  return firstArg.properties.some((prop) => {
+    if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop))
+      return !1;
+    return prop.name?.getText(firstArg.getSourceFile()).replace(/['"]/g, "") === "store";
+  });
+}
 export async function analyzeFileWithAST(file, cwd, content) {
   const ts = await loadTypeScript();
   if (!ts)
@@ -53,7 +63,10 @@ export async function analyzeFileWithAST(file, cwd, content) {
     issues,
     hasServerCall: !1,
     hasRouteCacheCall: !1,
+    hasRouteCacheExplicitStore: !1,
     hasCreateAuthCall: !1,
+    hasCreateMemorySessionStoreCall: !1,
+    hasCreateMemoryJobQueueCall: !1,
     hasRedirectCall: !1,
     hasCtxRedirectCall: !1,
     hasLegacyLoaderExport: moduleFacts.exportedNames.has("loader"),
@@ -73,8 +86,14 @@ export async function analyzeFileWithAST(file, cwd, content) {
         facts.hasServerCall = !0;
       if (isIdentifier(ts, node.expression, "createAuth"))
         facts.hasCreateAuthCall = !0;
+      if (isIdentifier(ts, node.expression, "createMemorySessionStore"))
+        facts.hasCreateMemorySessionStoreCall = !0;
+      if (isIdentifier(ts, node.expression, "createMemoryJobQueue"))
+        facts.hasCreateMemoryJobQueueCall = !0;
       if (isIdentifier(ts, node.expression, "routeCache")) {
         facts.hasRouteCacheCall = !0;
+        if (hasRouteCacheStore(ts, node))
+          facts.hasRouteCacheExplicitStore = !0;
         if (!hasRouteCacheIntent(ts, node))
           pushIssue(issues, seen, {
             code: "W904",

package/dist-pkg/cli/cmd-check.js

@@ -11,7 +11,7 @@ import {
   emitAIDiagnostic,
   emitAIEvent
 } from "../ai/index.js";
-import { loadAppConfig, resolveAIConfig } from "../runtime/app-config.js";
+import { loadAppConfig, resolveAIConfig, resolveRuntimeTopology } from "../runtime/app-config.js";
 const MAX_FILE_LINES = 500;
 async function getAllTsFiles(dir) {
   const files = [];
@@ -32,6 +32,25 @@ async function getAllTsFiles(dir) {
   }
   return files;
 }
+async function getTopLevelTsFiles(cwd) {
+  const files = [];
+  let entries;
+  try {
+    entries = await readdir(cwd);
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    if (entry === "node_modules" || entry === "dist" || entry === ".git" || entry === "routes" || entry === "shared" || entry === "middleware")
+      continue;
+    if (!entry.endsWith(".ts") && !entry.endsWith(".tsx"))
+      continue;
+    const fullPath = join(cwd, entry);
+    if ((await stat(fullPath)).isFile())
+      files.push(fullPath);
+  }
+  return files;
+}
 async function checkFileSize(file, cwd) {
   const issues = [], lines = (await readFile(file, "utf-8")).split(`
 `).length, rel = relative(cwd, file);
@@ -174,6 +193,54 @@ async function checkSecurityContracts(cwd, files, astFacts) {
     });
   return issues;
 }
+async function checkDistributedContracts(cwd, files, astFacts) {
+  const issues = [], appConfig = await loadAppConfig(cwd);
+  if (resolveRuntimeTopology(appConfig) !== "multi-instance")
+    return issues;
+  const hasDistributedRateLimiter = Boolean(appConfig.security?.rateLimit?.limiter), hasAIBridge = Boolean(appConfig.ai?.bridge?.url);
+  for (const file of files) {
+    const facts = astFacts.get(file);
+    if (!facts)
+      continue;
+    const rel = relative(cwd, file);
+    if (facts.hasCreateMemorySessionStoreCall)
+      issues.push({
+        code: "W917",
+        file: rel,
+        message: "multi-instance app uses createMemorySessionStore(), which is process-local only",
+        fix: "Use a distributed session store such as createRedisSessionStore(...) for multi-instance deployments"
+      });
+    if (facts.hasCreateMemoryJobQueueCall)
+      issues.push({
+        code: "W918",
+        file: rel,
+        message: "multi-instance app uses createMemoryJobQueue(), which does not provide durable cross-replica execution",
+        fix: "Use createRedisJobQueue(...) or another durable distributed queue backend for multi-instance deployments"
+      });
+    if (facts.hasRouteCacheCall && !facts.hasRouteCacheExplicitStore)
+      issues.push({
+        code: "W919",
+        file: rel,
+        message: "multi-instance app uses routeCache() without an explicit distributed store",
+        fix: "Pass store: createRedisCacheStore(...) (or another shared CacheStore) so cache entries stay coherent across replicas"
+      });
+  }
+  if (!hasDistributedRateLimiter)
+    issues.push({
+      code: "W920",
+      file: "app.config.ts",
+      message: "multi-instance app does not declare security.rateLimit.limiter",
+      fix: "Set security.rateLimit.limiter to a distributed limiter such as createRedisRateLimiter(...) to avoid per-process quota drift"
+    });
+  if ((appConfig.ai?.enabled ?? !1) && !hasAIBridge)
+    issues.push({
+      code: "W921",
+      file: "app.config.ts",
+      message: "multi-instance app enables AI observability without ai.bridge.url",
+      fix: "Keep local .gorsee artifacts for node-local triage, but add ai.bridge.url to forward events to a fleet-level aggregator"
+    });
+  return issues;
+}
 function checkImportContracts(cwd, astFacts) {
   const issues = [];
   for (const [file, facts] of astFacts) {
@@ -451,6 +518,7 @@ export async function checkProject(options = {}) {
   const files = await getAllTsFiles(paths.routesDir);
   files.push(...await getAllTsFiles(paths.sharedDir));
   files.push(...await getAllTsFiles(paths.middlewareDir));
+  files.push(...await getTopLevelTsFiles(cwd));
   const astFacts = await collectASTFacts(files, cwd);
   for (const file of files) {
     const sizeIssues = await checkFileSize(file, cwd), safetyIssues = await checkUnsafePatterns(file, cwd);
@@ -463,6 +531,9 @@ export async function checkProject(options = {}) {
   const importIssues = checkImportContracts(cwd, astFacts);
   for (const issue of importIssues)
     pushIssue(result, issue, strictSecurity);
+  const distributedIssues = await checkDistributedContracts(cwd, files, astFacts);
+  for (const issue of distributedIssues)
+    pushIssue(result, issue, strictSecurity);
   const dependencyIssues = await checkDependencyPolicy(cwd);
   for (const issue of dependencyIssues)
     pushIssue(result, issue, strictSecurity);

package/dist-pkg/cli/framework-md.js

@@ -109,6 +109,8 @@ export const cache = routeCache({
 
 - SQLite adapters are the default persistent single-node path
 - Redis adapters are the default multi-instance path
+- Set \`runtime.topology = "multi-instance"\` in \`app.config.ts\` when replicas share traffic; production then requires an explicit distributed \`security.rateLimit.limiter\`
+- Use \`createRedisJobQueue()\` for durable cross-replica job execution; \`createMemoryJobQueue()\` is single-node only
 - \`createNodeRedisLikeClient()\` and \`createIORedisLikeClient()\` normalize real Redis SDK clients to the framework adapter contract
 - \`routeCache()\` defaults to \`mode: "private"\` and varies by \`Cookie\`, \`Authorization\`, \`Accept\`, and \`X-Gorsee-Navigate\`
 - Use \`mode: "public"\` or \`mode: "shared"\` only for intentionally non-personalized cache entries
@@ -167,6 +169,7 @@ export default {
 - \`gorsee ai doctor\` clusters repeated failures by trace/request/file/route so agents can spot systemic regressions quickly
 - \`gorsee ai doctor\` and \`gorsee ai export\` also surface artifact regressions, so agents can reason about broken tarballs, VSIX files, build outputs, and deploy configs without separate tooling
 - Bridge delivery is best-effort only; a dead IDE bridge must never fail the request/build/check path
+- In multi-instance deployments, keep local \`.gorsee/*\` artifacts for node-local triage and add \`ai.bridge.url\` for fleet-level aggregation
 - Event schema carries \`requestId\`, \`traceId\`, \`spanId\`, \`route\`, \`code\`, \`file\`, \`line\`, and \`durationMs\`
 - Prefer AI events over scraped console logs when automating analysis
 - Use \`gorsee ai export --bundle\` when an agent needs a compact context packet plus root-cause-ranked code snippets

package/dist-pkg/prod.js

@@ -33,7 +33,9 @@ import { createProjectContext, resolveRuntimeEnv } from "./runtime/project.js";
 import {
   loadAppConfig,
   resolveAIConfig,
+  resolveRuntimeTopology,
   resolveRPCMiddlewares,
+  resolveSecurityRateLimit,
   resolveTrustedHosts,
   resolveTrustedForwardedHops,
   resolveTrustedOrigin,
@@ -284,14 +286,19 @@ async function loadProductionRuntimeState(options = {}) {
   await loadEnv(runtime.cwd);
   const envConfig = resolveRuntimeEnv(process.env);
   setLogLevel(envConfig.logLevel);
-  const manifest = await loadBuildManifest(runtime.paths.distDir);
+  const appConfig = await loadAppConfig(runtime.cwd, runtime.paths.appConfigFile), manifest = await loadBuildManifest(runtime.paths.distDir);
   log.info("loaded manifest", {
     routes: Object.keys(manifest.routes).length,
     built: manifest.buildTime,
     schemaVersion: manifest.schemaVersion,
     expectedSchemaVersion: BUILD_MANIFEST_SCHEMA_VERSION
   });
-  const routes = await createRouter(runtime.paths.routesDir), staticMap = buildStaticMap(routes), rateLimiter = createRateLimiter(envConfig.rateLimit, envConfig.rateWindow);
+  const routes = await createRouter(runtime.paths.routesDir), staticMap = buildStaticMap(routes), topology = resolveRuntimeTopology(appConfig), configuredRateLimit = resolveSecurityRateLimit(appConfig), rateLimiter = configuredRateLimit?.limiter ?? (topology === "multi-instance" ? null : createRateLimiter(configuredRateLimit?.maxRequests ?? envConfig.rateLimit, configuredRateLimit?.window ?? envConfig.rateWindow));
+  if (!rateLimiter)
+    throw Error([
+      "Multi-instance production runtime requires security.rateLimit.limiter in app.config.ts.",
+      "Use a distributed limiter such as createRedisRateLimiter(...) instead of the process-local default."
+    ].join(" "));
   return {
     cwd: runtime.cwd,
     routesDir: runtime.paths.routesDir,

package/dist-pkg/runtime/app-config.d.ts

@@ -1,7 +1,17 @@
 import type { MiddlewareFn } from "../server/middleware.js";
 import { type AIObservabilityConfig } from "../ai/index.js";
+import type { AsyncRateLimiter } from "../security/redis-rate-limit.js";
+import type { RateLimiter } from "../security/rate-limit.js";
+export interface AppSecurityRateLimitConfig {
+    maxRequests?: number;
+    window?: string;
+    limiter?: RateLimiter | AsyncRateLimiter;
+}
 export interface AppConfig {
     ai?: AIObservabilityConfig;
+    runtime?: {
+        topology?: RuntimeTopology;
+    };
     security?: {
         origin?: string;
         hosts?: string[];
@@ -10,14 +20,18 @@ export interface AppConfig {
             trustForwardedHeaders?: boolean;
             trustedForwardedHops?: number;
         };
+        rateLimit?: AppSecurityRateLimitConfig;
         rpc?: {
             middlewares?: MiddlewareFn[];
         };
     };
 }
 export type ProxyPreset = "none" | "reverse-proxy" | "vercel" | "netlify" | "fly" | "cloudflare";
+export type RuntimeTopology = "single-instance" | "multi-instance";
 export declare function loadAppConfig(cwd: string, explicitPath?: string): Promise<AppConfig>;
 export declare function resolveRPCMiddlewares(config: AppConfig, explicitMiddlewares?: MiddlewareFn[]): MiddlewareFn[] | undefined;
+export declare function resolveRuntimeTopology(config: AppConfig): RuntimeTopology;
+export declare function resolveSecurityRateLimit(config: AppConfig): AppSecurityRateLimitConfig | undefined;
 export declare function resolveAIConfig(cwd: string, config: AppConfig, explicitConfig?: AIObservabilityConfig): AIObservabilityConfig | undefined;
 export declare function resolveTrustedOrigin(config: AppConfig, env?: NodeJS.ProcessEnv): string | undefined;
 export declare function resolveTrustForwardedHeaders(config: AppConfig): boolean;

package/dist-pkg/runtime/app-config.js

@@ -11,7 +11,7 @@ export async function loadAppConfig(cwd, explicitPath) {
   for (const configPath of candidatePaths)
     try {
       const configStat = await stat(configPath);
-      return (await import(`${pathToFileURL(configPath).href}?t=${configStat.mtimeMs}`)).default ?? {};
+      return (await import(`${pathToFileURL(configPath).href}?t=${configStat.mtimeMs}-${Date.now()}`)).default ?? {};
     } catch {
       continue;
     }
@@ -23,6 +23,12 @@ export function resolveRPCMiddlewares(config, explicitMiddlewares) {
   const configMiddlewares = config.security?.rpc?.middlewares;
   return configMiddlewares && configMiddlewares.length > 0 ? configMiddlewares : void 0;
 }
+export function resolveRuntimeTopology(config) {
+  return config.runtime?.topology === "multi-instance" ? "multi-instance" : "single-instance";
+}
+export function resolveSecurityRateLimit(config) {
+  return config.security?.rateLimit;
+}
 export function resolveAIConfig(cwd, config, explicitConfig) {
   const merged = {
     ...config.ai ?? {},

package/dist-pkg/server/index.d.ts

@@ -15,6 +15,7 @@ export { createGuard, requireAuth, requireRole, allGuards, anyGuard } from "./gu
 export { pipe, when, forMethods, forPaths } from "./pipe.js";
 export { createNamespacedCacheStore } from "./cache-utils.js";
 export { createRedisCacheStore } from "./redis-cache-store.js";
+export { createRedisJobQueue, type RedisJobQueueOptions } from "./redis-job-queue.js";
 export { createScopedRPCRegistry } from "./rpc-utils.js";
 export { createSQLiteCacheStore } from "./sqlite-cache-store.js";
 export { createMemoryJobQueue, defineJob, type JobContext, type JobDefinition, type JobEnqueueOptions, type JobQueue, type JobRunResult, type EnqueuedJob } from "./jobs.js";

package/dist-pkg/server/index.js

@@ -42,6 +42,7 @@ export { createGuard, requireAuth, requireRole, allGuards, anyGuard } from "./gu
 export { pipe, when, forMethods, forPaths } from "./pipe.js";
 export { createNamespacedCacheStore } from "./cache-utils.js";
 export { createRedisCacheStore } from "./redis-cache-store.js";
+export { createRedisJobQueue } from "./redis-job-queue.js";
 export { createScopedRPCRegistry } from "./rpc-utils.js";
 export { createSQLiteCacheStore } from "./sqlite-cache-store.js";
 export { createMemoryJobQueue, defineJob } from "./jobs.js";

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

@@ -8,6 +8,7 @@ export interface RedisLikeClient {
     expire?(key: string, seconds: number): Awaitable<number>;
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
+    setnx?(key: string, value: string): Awaitable<number>;
 }
 export declare function buildRedisKey(prefix: string, key: string): string;
 export declare function stripRedisPrefix(prefix: string, key: string): string;
@@ -20,6 +21,7 @@ export interface NodeRedisClientLike {
     expire?(key: string, seconds: number): Awaitable<number>;
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
+    setnx?(key: string, value: string): Awaitable<number>;
 }
 export interface IORedisClientLike {
     get(key: string): Awaitable<string | null>;
@@ -30,6 +32,7 @@ export interface IORedisClientLike {
     expire?(key: string, seconds: number): Awaitable<number>;
     pttl?(key: string): Awaitable<number>;
     ttl?(key: string): Awaitable<number>;
+    setnx?(key: string, value: string): Awaitable<number>;
 }
 export declare function createNodeRedisLikeClient(client: NodeRedisClientLike): RedisLikeClient;
 export declare function createIORedisLikeClient(client: IORedisClientLike): RedisLikeClient;

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

@@ -14,7 +14,8 @@ export function createNodeRedisLikeClient(client) {
     incr: client.incr ? (key) => client.incr(key) : void 0,
     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
+    ttl: client.ttl ? (key) => client.ttl(key) : void 0,
+    setnx: client.setnx ? (key, value) => client.setnx(key, value) : void 0
   };
 }
 export function createIORedisLikeClient(client) {

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

@@ -0,0 +1,10 @@
+import type { JobDefinition, JobQueue } from "./jobs.js";
+import { type RedisLikeClient } from "./redis-client.js";
+interface RedisJobQueueOptions {
+    prefix?: string;
+    lockTtlSeconds?: number;
+    jobs?: Array<JobDefinition<unknown>>;
+    instanceId?: string;
+}
+export declare function createRedisJobQueue(client: RedisLikeClient, options?: RedisJobQueueOptions): JobQueue;
+export type { RedisJobQueueOptions };

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

@@ -0,0 +1,141 @@
+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;
+  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 = {
+        id,
+        name: job.name,
+        payload,
+        runAt: enqueueOptions.runAt ?? Date.now(),
+        attempts: 0,
+        maxAttempts: enqueueOptions.maxAttempts ?? 3,
+        backoffMs: enqueueOptions.backoffMs ?? 1000
+      };
+      await client.set(jobKey(prefix, id), JSON.stringify({
+        ...enqueued,
+        sequence
+      }));
+      return enqueued;
+    },
+    async runNext(now = Date.now()) {
+      const dueJobs = await listDueJobs(client, prefix, now);
+      for (const job of dueJobs) {
+        const lockKey = claimKey(prefix, job.id);
+        if (await client.setnx(lockKey, instanceId) !== 1)
+          continue;
+        await client.expire(lockKey, lockTtlSeconds);
+        try {
+          const current = await readStoredJob(client, prefix, job.id);
+          if (!current || current.runAt > now)
+            continue;
+          const handler = handlers.get(current.name);
+          if (!handler) {
+            await client.del(jobKey(prefix, current.id));
+            return {
+              id: current.id,
+              name: current.name,
+              status: "failed",
+              attempts: current.attempts + 1,
+              error: `Missing Redis job handler registration for "${current.name}"`
+            };
+          }
+          current.attempts += 1;
+          try {
+            await handler.handler(current.payload, {
+              attempt: current.attempts,
+              maxAttempts: current.maxAttempts
+            });
+            await client.del(jobKey(prefix, current.id));
+            return {
+              id: current.id,
+              name: current.name,
+              status: "completed",
+              attempts: current.attempts
+            };
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            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));
+              return {
+                id: current.id,
+                name: current.name,
+                status: "retrying",
+                attempts: current.attempts,
+                nextRunAt: current.runAt,
+                error: message
+              };
+            }
+            await client.del(jobKey(prefix, current.id));
+            return {
+              id: current.id,
+              name: current.name,
+              status: "failed",
+              attempts: current.attempts,
+              error: message
+            };
+          }
+        } finally {
+          await client.del(lockKey);
+        }
+      }
+      return null;
+    },
+    async drain(now = Date.now()) {
+      const results = [];
+      for (;; ) {
+        const result = await this.runNext(now);
+        if (!result)
+          return results;
+        results.push(result);
+      }
+    },
+    async size() {
+      return (await listStoredJobs(client, prefix)).length;
+    }
+  };
+}
+function jobKey(prefix, id) {
+  return buildRedisKey(prefix, id);
+}
+function claimKey(prefix, id) {
+  return buildRedisKey(`${prefix}:lock`, id);
+}
+async function listStoredJobs(client, prefix) {
+  const keys = await client.keys(`${prefix}:*`), jobs = [];
+  for (const key of keys) {
+    const visibleKey = stripRedisPrefix(prefix, key);
+    if (visibleKey.startsWith("lock:") || visibleKey === "__sequence")
+      continue;
+    const job = await readStoredJob(client, prefix, visibleKey);
+    if (job)
+      jobs.push(job);
+  }
+  return jobs;
+}
+async function listDueJobs(client, prefix, now) {
+  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) {
+  const raw = await client.get(jobKey(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));
+      return null;
+    }
+    return parsed;
+  } catch {
+    await client.del(jobKey(prefix, id));
+    return null;
+  }
+}

package/dist-pkg/server-entry.d.ts

@@ -13,6 +13,7 @@ export { log, setLogLevel } from "./log/index.js";
 export { buildAIHealthReport, buildAIContextBundle, buildIDEProjection, configureAIObservability, createAIMCPServer, createAIContextPacket, createAIBridgeHandler, createAIBridgeServer, createIDEProjectionWatcher, createLineReader, emitAIDiagnostic, emitAIEvent, createTraceIds, readAIDiagnosticsSnapshot, readAIEvents, renderAIContextBundleMarkdown, renderAIContextMarkdown, resolveAISessionPackPaths, resolveIDEProjectionPaths, resolveAIStorePaths, resolveAIObservabilityConfig, runWithAITrace, writeAISessionPack, writeIDEProjection, type AIMCPServerOptions, type AIContextPacket, type AIContextBundle, type AIContextSnippet, type AIHealthReport, type AIEvent, type AIEventSeverity, type IDEProjection, type IDEProjectionPaths, type IDEProjectionWatcher, type IDEProjectionWatcherOptions, type AISessionPackConfig, type AISessionPackPaths, type AIStorePaths, type AITraceContext, type AIDiagnostic, type AIObservabilityConfig, type AIBridgeConfig, type AIBridgeServer, type AIBridgeHandler, type AIBridgeServerOptions, type AIBridgeSnapshot, } from "./ai/index.js";
 export { createNodeRedisLikeClient, createIORedisLikeClient, deleteExpiredRedisKeys, type RedisLikeClient, type NodeRedisClientLike, type IORedisClientLike, } from "./server/redis-client.js";
 export { createMemoryJobQueue, defineJob, type JobContext, type JobDefinition, type JobEnqueueOptions, type JobQueue, type JobRunResult, type EnqueuedJob, } from "./server/jobs.js";
+export { createRedisJobQueue, type RedisJobQueueOptions } from "./server/redis-job-queue.js";
 /** @deprecated Prefer "gorsee/i18n" when locale contracts are the primary concern. */
 export { setupI18n, loadLocale, getLocale, getLocales, getDefaultLocale, getFallbackLocales, setLocale, t, plural, negotiateLocale, resolveLocaleFromPath, stripLocalePrefix, withLocalePath, buildHreflangLinks, formatNumber, formatDate, formatRelativeTime, type I18nConfig, type LocaleNegotiationInput, type LocaleNegotiationResult, } from "./i18n/index.js";
 /** @deprecated Prefer "gorsee/content" when content contracts are the primary concern. */

package/dist-pkg/server-entry.js

@@ -65,6 +65,7 @@ export {
   createMemoryJobQueue,
   defineJob
 } from "./server/jobs.js";
+export { createRedisJobQueue } from "./server/redis-job-queue.js";
 export {
   setupI18n,
   loadLocale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gorsee",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "AI-first reactive full-stack TypeScript framework for deterministic human and agent collaboration",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -21,7 +21,7 @@
     "web-framework"
   ],
   "bin": {
-    "gorsee": "dist-pkg/bin/gorsee.js"
+    "gorsee": "bin/gorsee.js"
   },
   "exports": {
     ".": "./dist-pkg/index.js",
@@ -58,6 +58,7 @@
     "./deploy": "./dist-pkg/deploy/index.js"
   },
   "files": [
+    "bin/",
     "dist-pkg/",
     "README.md",
     "LICENSE"