gorsee 0.2.11 → 0.2.12

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

@@ -0,0 +1,78 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { configureAIObservability, emitAIEvent } from "../ai/index.js";
+import { loadEnv } from "../env/index.js";
+import { loadAppConfig, resolveAIConfig, resolveAppMode } from "../runtime/app-config.js";
+import { createProjectContext } from "../runtime/project.js";
+export function parseWorkerFlags(args) {
+  const flags = {
+    entry: "workers/main.ts"
+  };
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg)
+      continue;
+    if (arg === "--entry" && args[index + 1])
+      flags.entry = args[++index];
+    else if (arg.startsWith("--entry="))
+      flags.entry = arg.slice(8);
+  }
+  return flags;
+}
+export async function runWorker(args, options = {}) {
+  const flags = parseWorkerFlags(args), { cwd } = createProjectContext(options);
+  await loadEnv(cwd);
+  const appConfig = await loadAppConfig(cwd), appMode = resolveAppMode(appConfig);
+  if (appMode !== "server") {
+    console.error(`
+  Error: \`gorsee worker\` is only available for server-mode apps. Current app.mode is "${appMode}".
+`);
+    process.exit(1);
+  }
+  configureAIObservability(resolveAIConfig(cwd, appConfig));
+  const entryPath = join(cwd, flags.entry);
+  try {
+    await stat(entryPath);
+  } catch {
+    console.error(`
+  Error: Worker entry not found: ${flags.entry}
+`);
+    process.exit(1);
+  }
+  await emitAIEvent({
+    kind: "worker.command.start",
+    severity: "info",
+    source: "cli",
+    message: "starting worker entry",
+    data: {
+      entry: flags.entry,
+      appMode
+    }
+  });
+  try {
+    await import(pathToFileURL(entryPath).href);
+    await emitAIEvent({
+      kind: "worker.command.finish",
+      severity: "info",
+      source: "cli",
+      message: "worker entry finished",
+      data: {
+        entry: flags.entry,
+        appMode
+      }
+    });
+  } catch (error) {
+    await emitAIEvent({
+      kind: "worker.command.error",
+      severity: "error",
+      source: "cli",
+      message: error instanceof Error ? error.message : String(error),
+      data: {
+        entry: flags.entry,
+        appMode
+      }
+    });
+    throw error;
+  }
+}

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

@@ -6,7 +6,7 @@ export function generateFrameworkMD(projectName) {
 
 ## Product Identity
 
-Gorsee is an AI-first reactive full-stack framework designed for deterministic collaboration between humans and coding agents.
+Gorsee is an AI-first application platform designed for deterministic collaboration between humans and coding agents across frontend, fullstack, and server systems.
 
 Treat it as a mature product framework:
 
@@ -16,6 +16,12 @@ Treat it as a mature product framework:
 
 The framework prefers one clear path, strict contracts, and product-grade discipline over flexibility for its own sake.
 
+Canonical modes:
+
+- \`frontend\` for browser-first prerendered apps
+- \`fullstack\` for the canonical UI + server path
+- \`server\` for API-first and service-oriented systems
+
 ## Quick Reference
 
 \`\`\`
@@ -110,7 +116,11 @@ 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
+- Use \`createRedisJobQueue()\` for durable cross-replica job execution; when the Redis client exposes sorted-set primitives Gorsee uses indexed due scans and renews long-running execution leases, while \`createMemoryJobQueue()\` remains single-node only
+- Queue instances expose \`get(id)\`, \`peek(limit)\`, and \`cancel(id)\` for operator-facing inspection and pre-run cancellation of queued jobs
+- Queue instances also expose bounded terminal history via \`recent(limit)\`, dead-letter inspection via \`failures(limit)\`, and controlled recovery with \`retryFailed(id)\`
+- Queue lifecycle emits structured AI events: \`job.enqueue\`, \`job.start\`, \`job.retry\`, \`job.complete\`, \`job.fail\`, \`job.cancel\`, and \`job.dead-letter.retry\`
+- Use \`defineWorkerService()\` + \`runWorkerService()\` for long-running server-mode workers with explicit ready/heartbeat/stop semantics
 - \`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
@@ -165,7 +175,7 @@ export default {
 - \`.gorsee/ai-diagnostics.json\` keeps the latest error/warning snapshot for fast IDE polling
 - \`.gorsee/ide/diagnostics.json\`, \`.gorsee/ide/events.json\`, and \`.gorsee/ide/context.md\` are editor-facing projections produced by \`gorsee ai ide-sync\`
 - \`.gorsee/ide/events.json\` now includes \`artifactRegressions\` plus event-level \`artifact\` / \`version\` metadata for release/deploy/build drift
-- \`.gorsee/agent/latest.json\` and \`.gorsee/agent/latest.md\` are session packs for agents; they can be generated manually with \`gorsee ai pack\` or automatically after error/build/check triggers
+- \`.gorsee/agent/latest.json\` and \`.gorsee/agent/latest.md\` are session packs for agents; \`.gorsee/agent/deploy-summary.json\`, \`.gorsee/agent/release-brief.json\`, \`.gorsee/agent/incident-brief.json\`, and \`.gorsee/agent/incident-snapshot.json\` are grounded operational artifacts written alongside them
 - \`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
@@ -200,6 +210,7 @@ export default {
 ## Product DX References
 
 - Use \`docs/STARTER_ONBOARDING.md\` to choose the right app class
+- Use \`docs/APPLICATION_MODES.md\` when choosing or changing \`app.mode\`
 - Use \`docs/MIGRATION_GUIDE.md\` when cleaning up compatibility imports
 - Use \`docs/UPGRADE_PLAYBOOK.md\` before release-channel or contract upgrades
 - Use \`docs/DEPLOY_TARGET_GUIDE.md\` before committing to a deploy target
@@ -323,7 +334,7 @@ export default {
     csp: true,
     hsts: true,
     csrf: true,
-    rateLimit: { requests: 100, window: "1m" },
+    rateLimit: { maxRequests: 100, window: "1m" },
   },
   // RPC is a separate boundary from route _middleware.ts
   // security: { rpc: { middlewares: [auth.protect(), createCSRFMiddleware(process.env.SESSION_SECRET!)] } },
@@ -358,6 +369,7 @@ export default {
 gorsee dev          Start dev server
 gorsee build        Production build
 gorsee check        Type + safety + structure check
+gorsee worker       Run canonical server-mode worker entry
 gorsee check --rewrite-imports --rewrite-loaders
                     Normalize canonical imports and loader aliases before auditing
 gorsee ai framework Export canonical framework context for cold-start agents

package/dist-pkg/cli/index.js

@@ -3,6 +3,7 @@ const args = process.argv.slice(2), command = args[0], COMMANDS = {
   dev: "Start development server with HMR",
   build: "Production build (client + server)",
   start: "Start production server",
+  worker: "Run a server-mode worker entry",
   check: "Check project: types, safety, structure, optional canonical autofix",
   routes: "List all routes with render modes",
   migrate: "Run database migrations",
@@ -33,6 +34,10 @@ async function main() {
       const { runStart } = await import("./cmd-start.js");
       await runStart(args.slice(1));
       break;
+    case "worker":
+      const { runWorker } = await import("./cmd-worker.js");
+      await runWorker(args.slice(1));
+      break;
     case "check":
       const { runCheck } = await import("./cmd-check.js");
       await runCheck(args.slice(1));

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

@@ -7,7 +7,11 @@ export interface AppSecurityRateLimitConfig {
     window?: string;
     limiter?: RateLimiter | AsyncRateLimiter;
 }
+export type AppMode = "frontend" | "fullstack" | "server";
 export interface AppConfig {
+    app?: {
+        mode?: AppMode;
+    };
     ai?: AIObservabilityConfig;
     runtime?: {
         topology?: RuntimeTopology;
@@ -28,6 +32,7 @@ export interface AppConfig {
 }
 export type ProxyPreset = "none" | "reverse-proxy" | "vercel" | "netlify" | "fly" | "cloudflare";
 export type RuntimeTopology = "single-instance" | "multi-instance";
+export declare function resolveAppMode(config: AppConfig): AppMode;
 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;

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

@@ -1,7 +1,17 @@
-import { stat } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { resolveAIObservabilityConfig } from "../ai/index.js";
+export function resolveAppMode(config) {
+  switch (config.app?.mode) {
+    case "frontend":
+    case "server":
+      return config.app.mode;
+    case "fullstack":
+    default:
+      return "fullstack";
+  }
+}
 export async function loadAppConfig(cwd, explicitPath) {
   const candidatePaths = explicitPath ? [explicitPath] : [
     join(cwd, "app.config.ts"),
@@ -10,8 +20,13 @@ 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}-${Date.now()}`)).default ?? {};
+      const configStat = await stat(configPath), ext = extname(configPath) || ".ts", configDir = dirname(configPath), configBase = basename(configPath, ext), tempConfigPath = join(configDir, `.${configBase}.gorsee-load-${process.pid}-${configStat.mtimeMs}-${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`);
+      try {
+        await writeFile(tempConfigPath, await readFile(configPath, "utf-8"), "utf-8");
+        return (await import(pathToFileURL(tempConfigPath).href)).default ?? {};
+      } finally {
+        await rm(tempConfigPath, { force: !0 }).catch(() => {});
+      }
     } catch {
       continue;
     }
@@ -30,9 +45,15 @@ export function resolveSecurityRateLimit(config) {
   return config.security?.rateLimit;
 }
 export function resolveAIConfig(cwd, config, explicitConfig) {
+  if (!config.ai && !explicitConfig)
+    return;
   const merged = {
     ...config.ai ?? {},
-    ...explicitConfig ?? {}
+    ...explicitConfig ?? {},
+    app: explicitConfig?.app ?? config.ai?.app ?? {
+      mode: resolveAppMode(config),
+      runtimeTopology: resolveRuntimeTopology(config)
+    }
   };
   if (Object.keys(merged).length === 0)
     return;

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

@@ -18,7 +18,8 @@ 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";
+export { createMemoryJobQueue, defineJob, type JobContext, type JobDefinition, type JobEnqueueOptions, type JobRetryOptions, type JobQueue, type JobRunResult, type EnqueuedJob, type QueuedJobRecord, type TerminalJobRecord, type MemoryJobQueueOptions } from "./jobs.js";
+export { defineWorkerService, runWorkerService, type WorkerServiceContext, type WorkerServiceDefinition, type WorkerServiceStartHandle, type RunWorkerServiceOptions, type RunningWorkerService } from "./worker-service.js";
 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";
 export { loadContentCollection, parseFrontmatter, extractExcerpt, queryContent, getContentEntryBySlug, type ContentCollectionOptions, type ContentEntry, type ContentQueryOptions, } from "../content/index.js";
 export { type RedisLikeClient, type NodeRedisClientLike, type IORedisClientLike, createNodeRedisLikeClient, createIORedisLikeClient, deleteExpiredRedisKeys, } from "./redis-client.js";

package/dist-pkg/server/index.js

@@ -46,6 +46,7 @@ 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";
+export { defineWorkerService, runWorkerService } from "./worker-service.js";
 export {
   setupI18n,
   loadLocale,

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

@@ -1,4 +1,5 @@
 type Awaitable<T> = T | Promise<T>;
+export type JobQueueKind = "memory" | "redis";
 export interface JobContext {
     attempt: number;
     maxAttempts: number;
@@ -12,6 +13,8 @@ export interface JobEnqueueOptions {
     maxAttempts?: number;
     backoffMs?: number;
 }
+export interface JobRetryOptions extends JobEnqueueOptions {
+}
 export interface EnqueuedJob<Payload = unknown> {
     id: string;
     name: string;
@@ -22,6 +25,10 @@ export interface EnqueuedJob<Payload = unknown> {
     backoffMs: number;
     lastError?: string;
 }
+export interface QueuedJobRecord<Payload = unknown> extends EnqueuedJob<Payload> {
+    createdAt: number;
+    updatedAt: number;
+}
 export interface JobRunResult {
     id: string;
     name: string;
@@ -30,12 +37,39 @@ export interface JobRunResult {
     nextRunAt?: number;
     error?: string;
 }
+export interface TerminalJobRecord<Payload = unknown> extends QueuedJobRecord<Payload> {
+    status: "completed" | "failed";
+    finishedAt: number;
+}
+export interface MemoryJobQueueOptions {
+    historyLimit?: number;
+}
+interface JobLifecycleEventInput {
+    kind: "job.enqueue" | "job.start" | "job.retry" | "job.complete" | "job.fail" | "job.cancel" | "job.dead-letter.retry";
+    severity: "info" | "warn" | "error";
+    queue: JobQueueKind;
+    id: string;
+    name: string;
+    attempts?: number;
+    maxAttempts?: number;
+    runAt?: number;
+    nextRunAt?: number;
+    error?: string;
+    workerInstanceId?: string;
+}
 export interface JobQueue {
     enqueue<Payload>(job: JobDefinition<Payload>, payload: Payload, options?: JobEnqueueOptions): Promise<EnqueuedJob<Payload>>;
     runNext(now?: number): Promise<JobRunResult | null>;
     drain(now?: number): Promise<JobRunResult[]>;
     size(): Promise<number>;
+    get(id: string): Promise<QueuedJobRecord | null>;
+    peek(limit?: number): Promise<QueuedJobRecord[]>;
+    cancel(id: string): Promise<boolean>;
+    recent(limit?: number): Promise<TerminalJobRecord[]>;
+    failures(limit?: number): Promise<TerminalJobRecord[]>;
+    retryFailed(id: string, options?: JobRetryOptions): Promise<EnqueuedJob | null>;
 }
 export declare function defineJob<Payload>(name: string, handler: (payload: Payload, context: JobContext) => Awaitable<void>): JobDefinition<Payload>;
-export declare function createMemoryJobQueue(): JobQueue;
+export declare function emitJobLifecycleEvent(input: JobLifecycleEventInput): Promise<void>;
+export declare function createMemoryJobQueue(options?: MemoryJobQueueOptions): JobQueue;
 export {};

package/dist-pkg/server/jobs.js

@@ -1,15 +1,75 @@
+import { emitAIEvent } from "../ai/index.js";
 export function defineJob(name, handler) {
   return { name, handler };
 }
-export function createMemoryJobQueue() {
-  const jobs = [];
+export async function emitJobLifecycleEvent(input) {
+  await emitAIEvent({
+    kind: input.kind,
+    severity: input.severity,
+    source: "runtime",
+    message: buildJobLifecycleMessage(input),
+    data: {
+      queue: input.queue,
+      jobId: input.id,
+      jobName: input.name,
+      attempts: input.attempts,
+      maxAttempts: input.maxAttempts,
+      runAt: input.runAt,
+      nextRunAt: input.nextRunAt,
+      workerInstanceId: input.workerInstanceId,
+      error: input.error
+    }
+  });
+}
+function buildJobLifecycleMessage(input) {
+  switch (input.kind) {
+    case "job.enqueue":
+      return `queued job ${input.name}`;
+    case "job.start":
+      return `started job ${input.name}`;
+    case "job.retry":
+      return `retrying job ${input.name}`;
+    case "job.complete":
+      return `completed job ${input.name}`;
+    case "job.fail":
+      return `failed job ${input.name}`;
+    case "job.cancel":
+      return `cancelled job ${input.name}`;
+    case "job.dead-letter.retry":
+      return `requeued failed job ${input.name}`;
+    default:
+      return `job lifecycle event for ${input.name}`;
+  }
+}
+export function createMemoryJobQueue(options = {}) {
+  const jobs = [], history = [];
   let sequence = 0;
+  const historyLimit = options.historyLimit ?? 100;
   function sortJobs() {
     jobs.sort((a, b) => a.runAt - b.runAt || a.sequence - b.sequence);
   }
+  function pushHistory(entry, status) {
+    history.unshift({
+      id: entry.id,
+      name: entry.name,
+      payload: entry.payload,
+      runAt: entry.runAt,
+      attempts: entry.attempts,
+      maxAttempts: entry.maxAttempts,
+      backoffMs: entry.backoffMs,
+      lastError: entry.lastError,
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+      finishedAt: Date.now(),
+      status,
+      job: entry.job
+    });
+    if (history.length > historyLimit)
+      history.length = historyLimit;
+  }
   return {
     async enqueue(job, payload, options = {}) {
-      const enqueued = {
+      const now = Date.now(), enqueued = {
         id: crypto.randomUUID(),
         name: job.name,
         payload,
@@ -17,11 +77,23 @@ export function createMemoryJobQueue() {
         attempts: 0,
         maxAttempts: options.maxAttempts ?? 3,
         backoffMs: options.backoffMs ?? 1000,
+        createdAt: now,
+        updatedAt: now,
         job,
         sequence: sequence++
       };
       jobs.push(enqueued);
       sortJobs();
+      await emitJobLifecycleEvent({
+        kind: "job.enqueue",
+        severity: "info",
+        queue: "memory",
+        id: enqueued.id,
+        name: enqueued.name,
+        attempts: enqueued.attempts,
+        maxAttempts: enqueued.maxAttempts,
+        runAt: enqueued.runAt
+      });
       return enqueued;
     },
     async runNext(now = Date.now()) {
@@ -31,11 +103,33 @@ export function createMemoryJobQueue() {
         return null;
       const entry = jobs.splice(nextIndex, 1)[0];
       entry.attempts += 1;
+      await emitJobLifecycleEvent({
+        kind: "job.start",
+        severity: "info",
+        queue: "memory",
+        id: entry.id,
+        name: entry.name,
+        attempts: entry.attempts,
+        maxAttempts: entry.maxAttempts,
+        runAt: entry.runAt
+      });
       try {
         await entry.job.handler(entry.payload, {
           attempt: entry.attempts,
           maxAttempts: entry.maxAttempts
         });
+        entry.updatedAt = Date.now();
+        pushHistory(entry, "completed");
+        await emitJobLifecycleEvent({
+          kind: "job.complete",
+          severity: "info",
+          queue: "memory",
+          id: entry.id,
+          name: entry.name,
+          attempts: entry.attempts,
+          maxAttempts: entry.maxAttempts,
+          runAt: entry.runAt
+        });
         return {
           id: entry.id,
           name: entry.name,
@@ -47,8 +141,21 @@ export function createMemoryJobQueue() {
         entry.lastError = message;
         if (entry.attempts < entry.maxAttempts) {
           entry.runAt = now + entry.backoffMs * entry.attempts;
+          entry.updatedAt = Date.now();
           jobs.push(entry);
           sortJobs();
+          await emitJobLifecycleEvent({
+            kind: "job.retry",
+            severity: "warn",
+            queue: "memory",
+            id: entry.id,
+            name: entry.name,
+            attempts: entry.attempts,
+            maxAttempts: entry.maxAttempts,
+            runAt: now,
+            nextRunAt: entry.runAt,
+            error: message
+          });
           return {
             id: entry.id,
             name: entry.name,
@@ -58,6 +165,19 @@ export function createMemoryJobQueue() {
             error: message
           };
         }
+        entry.updatedAt = Date.now();
+        pushHistory(entry, "failed");
+        await emitJobLifecycleEvent({
+          kind: "job.fail",
+          severity: "error",
+          queue: "memory",
+          id: entry.id,
+          name: entry.name,
+          attempts: entry.attempts,
+          maxAttempts: entry.maxAttempts,
+          runAt: entry.runAt,
+          error: message
+        });
         return {
           id: entry.id,
           name: entry.name,
@@ -78,6 +198,109 @@ export function createMemoryJobQueue() {
     },
     async size() {
       return jobs.length;
+    },
+    async get(id) {
+      const job = jobs.find((entry) => entry.id === id);
+      if (!job)
+        return null;
+      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
+      };
+    },
+    async peek(limit = Number.POSITIVE_INFINITY) {
+      sortJobs();
+      return jobs.slice(0, limit).map((job) => ({
+        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
+      }));
+    },
+    async cancel(id) {
+      const index = jobs.findIndex((entry) => entry.id === id);
+      if (index === -1)
+        return !1;
+      const [entry] = jobs.splice(index, 1);
+      if (entry)
+        await emitJobLifecycleEvent({
+          kind: "job.cancel",
+          severity: "info",
+          queue: "memory",
+          id: entry.id,
+          name: entry.name,
+          attempts: entry.attempts,
+          maxAttempts: entry.maxAttempts,
+          runAt: entry.runAt
+        });
+      return !0;
+    },
+    async recent(limit = 50) {
+      return history.slice(0, limit).map((entry) => ({
+        id: entry.id,
+        name: entry.name,
+        payload: entry.payload,
+        runAt: entry.runAt,
+        attempts: entry.attempts,
+        maxAttempts: entry.maxAttempts,
+        backoffMs: entry.backoffMs,
+        lastError: entry.lastError,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+        finishedAt: entry.finishedAt,
+        status: entry.status
+      }));
+    },
+    async failures(limit = 50) {
+      return history.filter((entry) => entry.status === "failed").slice(0, limit).map((entry) => ({
+        id: entry.id,
+        name: entry.name,
+        payload: entry.payload,
+        runAt: entry.runAt,
+        attempts: entry.attempts,
+        maxAttempts: entry.maxAttempts,
+        backoffMs: entry.backoffMs,
+        lastError: entry.lastError,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+        finishedAt: entry.finishedAt,
+        status: entry.status
+      }));
+    },
+    async retryFailed(id, options = {}) {
+      const failedEntry = history.find((entry) => entry.id === id && entry.status === "failed");
+      if (!failedEntry)
+        return null;
+      const retried = await this.enqueue(failedEntry.job, failedEntry.payload, {
+        runAt: options.runAt ?? Date.now(),
+        maxAttempts: options.maxAttempts ?? failedEntry.maxAttempts,
+        backoffMs: options.backoffMs ?? failedEntry.backoffMs
+      });
+      await emitJobLifecycleEvent({
+        kind: "job.dead-letter.retry",
+        severity: "warn",
+        queue: "memory",
+        id: retried.id,
+        name: retried.name,
+        attempts: retried.attempts,
+        maxAttempts: retried.maxAttempts,
+        runAt: retried.runAt
+      });
+      return retried;
     }
   };
 }

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

@@ -1,4 +1,5 @@
 export declare const BUILD_MANIFEST_SCHEMA_VERSION: 1;
+export declare const RELEASE_ARTIFACT_SCHEMA_VERSION: 1;
 export interface BuildManifestRoute {
     js?: string;
     hasLoader: boolean;
@@ -6,13 +7,42 @@ export interface BuildManifestRoute {
 }
 export interface BuildManifest {
     schemaVersion: number;
+    appMode?: "frontend" | "fullstack" | "server";
     routes: Record<string, BuildManifestRoute>;
     chunks: string[];
     prerendered: string[];
     buildTime: string;
 }
+export interface ReleaseArtifactSummary {
+    routeCount: number;
+    clientAssetCount: number;
+    prerenderedCount: number;
+    serverEntryCount: number;
+}
+export interface ReleaseArtifactRuntime {
+    kind: "frontend-static" | "fullstack-runtime" | "server-runtime";
+    processEntrypoints: string[];
+    handlerEntrypoints: string[];
+    workerEntrypoint?: string;
+}
+export interface ReleaseArtifactArtifacts {
+    buildManifest: string;
+    clientAssets: string[];
+    serverEntries: string[];
+    prerenderedHtml: string[];
+}
+export interface ReleaseArtifact {
+    schemaVersion: number;
+    appMode: "frontend" | "fullstack" | "server";
+    generatedAt: string;
+    summary: ReleaseArtifactSummary;
+    runtime: ReleaseArtifactRuntime;
+    artifacts: ReleaseArtifactArtifacts;
+}
 export declare function loadBuildManifest(distDir: string): Promise<BuildManifest>;
+export declare function loadReleaseArtifact(distDir: string): Promise<ReleaseArtifact>;
 export declare function parseBuildManifest(raw: string): BuildManifest;
+export declare function parseReleaseArtifact(raw: string): ReleaseArtifact;
 export declare function getRouteBuildEntry(manifest: BuildManifest, pathname: string): BuildManifestRoute | undefined;
 export declare function getClientBundleForRoute(manifest: BuildManifest, pathname: string): string | undefined;
 export declare function isPrerenderedRoute(manifest: BuildManifest, pathname: string): boolean;