@ismaelsoilet/synapsejs 1.1.0

package/src/core/image-optimizer.ts

@@ -0,0 +1,83 @@
+/**
+ * SynapseJS - On-Demand Image Optimizer
+ *
+ * Provides dynamic, safe image resizing and format conversion.
+ * Uses dynamic import for `sharp` so Docker Alpine environments without
+ * heavy native C/C++ compilation overhead fall back gracefully to passthrough
+ * without crashing or breaking the runtime.
+ */
+
+export interface ImageOptimizationOptions {
+  width?: number;
+  height?: number;
+  quality?: number;
+  format?: 'webp' | 'jpeg' | 'png' | 'avif';
+}
+
+export interface ImageOptimizationResult {
+  data: Uint8Array;
+  contentType: string;
+  isOptimized: boolean;
+  engine: 'sharp' | 'passthrough';
+}
+
+/**
+ * Optimizes an image buffer on-demand.
+ * If `sharp` is available in node_modules, resizes/converts formats.
+ * If `sharp` is absent (Air-Gap mode / minimal container), returns input unaltered.
+ */
+export async function optimizeImage(
+  input: Uint8Array | ArrayBuffer | Buffer,
+  contentType: string,
+  options: ImageOptimizationOptions = {}
+): Promise<ImageOptimizationResult> {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input as Uint8Array);
+
+  try {
+    // Dynamic import: if sharp is not installed, does not throw unhandled exception
+    const sharpPkg = 'sharp';
+    // biome-ignore lint/suspicious/noExplicitAny: optional native module boundary
+    const sharpModule: any = await import(sharpPkg).then((m) => m.default || m).catch(() => null);
+
+    if (sharpModule) {
+      let pipeline = sharpModule(buf);
+
+      if (options.width || options.height) {
+        pipeline = pipeline.resize({
+          width: options.width,
+          height: options.height,
+          fit: 'inside',
+          withoutEnlargement: true
+        });
+      }
+
+      const targetFormat = options.format || 'webp';
+      if (targetFormat === 'webp') {
+        pipeline = pipeline.webp({ quality: options.quality || 80 });
+      } else if (targetFormat === 'jpeg') {
+        pipeline = pipeline.jpeg({ quality: options.quality || 80 });
+      } else if (targetFormat === 'png') {
+        pipeline = pipeline.png({ quality: options.quality || 80 });
+      } else if (targetFormat === 'avif') {
+        pipeline = pipeline.avif({ quality: options.quality || 80 });
+      }
+
+      const optimizedBuffer = await pipeline.toBuffer();
+      return {
+        data: new Uint8Array(optimizedBuffer),
+        contentType: `image/${targetFormat}`,
+        isOptimized: true,
+        engine: 'sharp'
+      };
+    }
+  } catch {
+    // Fall back to passthrough if native binary fails to execute
+  }
+
+  return {
+    data: new Uint8Array(buf),
+    contentType: contentType || 'application/octet-stream',
+    isOptimized: false,
+    engine: 'passthrough'
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,14 @@
+export * from './action-context';
+export * from './config';
+export * from './database-client';
+export * from './database-factory';
+export * from './image-optimizer';
+export * from './jobs';
+export * from './machine-types';
+export * from './postgres-client';
+export * from './postgres-queue';
+export * from './query-builder';
+export * from './session-context';
+export * from './session-token';
+export * from './sqlite-client';
+export * from './storage';

package/src/core/jobs.ts

@@ -0,0 +1,53 @@
+/**
+ * SynapseJS - Type-Safe Background Jobs Contract
+ *
+ * Jobs can be defined inside slices or shared modules without breaking Locality of Behavior:
+ * export const sendWelcomeEmailJob = defineJob({
+ *   name: 'send-welcome-email',
+ *   handler: async (payload: { email: string }, ctx) => { ... }
+ * });
+ */
+
+import type { ActionContext } from './action-context';
+
+export type JobHandlerFn<TPayload = unknown> = (payload: TPayload, ctx: ActionContext) => Promise<void>;
+
+export interface JobDefinition<TPayload = unknown> {
+  /** Unique name identifier for the job */
+  readonly name: string;
+  /** Async execution handler receiving the typed payload and ActionContext */
+  readonly handler: JobHandlerFn<TPayload>;
+  /** Maximum retry attempts before marking the job as permanently failed (default: 3) */
+  readonly retryLimit?: number;
+  /** Initial backoff in seconds for exponential backoff retries (default: 5) */
+  readonly backoffSeconds?: number;
+  /** Optional schema validator (e.g. TypeBox schema) */
+  readonly schema?: unknown;
+}
+
+export interface JobOptions<TPayload = unknown> {
+  name: string;
+  handler?: JobHandlerFn<TPayload>;
+  perform?: JobHandlerFn<TPayload>;
+  retryLimit?: number;
+  backoffSeconds?: number;
+  schema?: unknown;
+}
+
+/**
+ * Declares a background job definition with type safety.
+ */
+export function defineJob<TPayload = unknown>(options: JobOptions<TPayload>): JobDefinition<TPayload> {
+  const handler = options.handler || options.perform;
+  if (!handler) {
+    throw new Error(`Job "${options.name}" must specify either a handler or perform function.`);
+  }
+
+  return Object.freeze({
+    name: options.name,
+    handler,
+    retryLimit: options.retryLimit ?? 3,
+    backoffSeconds: options.backoffSeconds ?? 5,
+    schema: options.schema
+  });
+}

package/src/core/machine-types.ts

@@ -0,0 +1,75 @@
+/**
+ * SynapseJS - Machine-Centric Types & Deterministic Error Modeling
+ *
+ * Eradicates hidden control flow and 'throw new Error' side effects.
+ * Forces both LLMs and compilers to explicitly map success and failure
+ * execution paths via discriminated unions.
+ */
+import { FormatRegistry } from '@sinclair/typebox';
+
+// Register standard formats out-of-the-box for AI agents
+if (!FormatRegistry.Has('email')) {
+  FormatRegistry.Set('email', (val) => typeof val === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val));
+}
+if (!FormatRegistry.Has('uuid')) {
+  FormatRegistry.Set(
+    'uuid',
+    (val) => typeof val === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(val)
+  );
+}
+
+export type Ok<T> = {
+  readonly ok: true;
+  readonly value: T;
+};
+
+export type Err<E> = {
+  readonly ok: false;
+  readonly error: E;
+};
+
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export function Ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+export function Err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result.ok === true;
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return result.ok === false;
+}
+
+export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
+  return result.ok ? result.value : fallback;
+}
+
+export function map<T, E, U>(result: Result<T, E>, fn: (val: T) => U): Result<U, E> {
+  if (result.ok) {
+    return Ok(fn(result.value));
+  }
+  return result;
+}
+
+export function mapErr<T, E, F>(result: Result<T, E>, fn: (err: E) => F): Result<T, F> {
+  if (!result.ok) {
+    return Err(fn(result.error));
+  }
+  return result;
+}
+
+export type Option<T> = { readonly hasValue: true; readonly value: T } | { readonly hasValue: false };
+
+export function Some<T>(value: T): Option<T> {
+  return { hasValue: true, value };
+}
+
+export function None<T = never>(): Option<T> {
+  return { hasValue: false };
+}

package/src/core/oracle.ts

@@ -0,0 +1,20 @@
+/**
+ * SynapseJS - Slice Oracle Contract
+ *
+ * A slice owns its invariants. The oracle is plain data + functions so it never
+ * pulls a test library into production code: the runner registers each case with
+ * Bun's real test runner from a generated companion file.
+ */
+
+export interface SliceOracleCase {
+  name: string;
+  run: () => unknown | Promise<unknown>;
+}
+
+export interface SliceOracle {
+  description?: string;
+  /** Preferred shape: one named case per invariant, for per-invariant reporting. */
+  cases?: SliceOracleCase[];
+  /** Legacy shape: a single unnamed routine. Reported as one case. */
+  run?: () => unknown | Promise<unknown>;
+}

package/src/core/postgres-client.ts

@@ -0,0 +1,164 @@
+/**
+ * SynapseJS - PostgreSQL Database Driver (postgres.js)
+ *
+ * Provides production-ready, pooled, high-performance PostgreSQL persistence
+ * implementing the core DatabaseClient contract.
+ */
+
+import postgres from 'postgres';
+import {
+  compileDelete,
+  compileInsert,
+  compileSelect,
+  compileTaggedSql,
+  compileUpdate,
+  type DatabaseClient,
+  nestJoinedRow,
+  type QueryOptions,
+  type WhereCondition
+} from './database-client';
+
+export class PostgresDatabaseClient implements DatabaseClient {
+  private client: postgres.Sql;
+
+  constructor(connectionString: string, options?: postgres.Options<any>) {
+    this.client = postgres(connectionString, {
+      max: options?.max || 10,
+      idle_timeout: options?.idle_timeout || 30,
+      // Notices are noise for a machine consumer: `stdout` must carry only the
+      // command's JSON result.
+      onnotice: () => {},
+      ...options
+    });
+  }
+
+  async query<T = unknown>(queryStr: string, params: unknown[] = []): Promise<T[]> {
+    // postgres.js unsafe executes raw SQL with parameter bindings
+    const result = await this.client.unsafe(queryStr, params as any[]);
+    return result as unknown as T[];
+  }
+
+  async queryOne<T = unknown>(queryStr: string, params: unknown[] = []): Promise<T | null> {
+    const results = await this.query<T>(queryStr, params);
+    return results.length > 0 ? results[0] : null;
+  }
+
+  async sql<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]> {
+    const { text, params } = compileTaggedSql(strings, ...values);
+    return this.query<T>(text, params);
+  }
+
+  async sqlOne<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T | null> {
+    const { text, params } = compileTaggedSql(strings, ...values);
+    return this.queryOne<T>(text, params);
+  }
+
+  async findMany<T = unknown>(table: string, options?: QueryOptions): Promise<T[]> {
+    const { sql, params } = compileSelect(table, options);
+    const rows = await this.query<Record<string, unknown>>(sql, params);
+    if (options?.join && options.join.length > 0) {
+      return rows.map((r) => nestJoinedRow<T>(r, options.join));
+    }
+    return rows as unknown as T[];
+  }
+
+  async findOne<T = unknown>(table: string, options?: QueryOptions): Promise<T | null> {
+    const opts = { ...options, limit: 1 };
+    const { sql, params } = compileSelect(table, opts);
+    const row = await this.queryOne<Record<string, unknown>>(sql, params);
+    if (!row) return null;
+    if (options?.join && options.join.length > 0) {
+      return nestJoinedRow<T>(row, options.join);
+    }
+    return row as unknown as T;
+  }
+
+  async insert<T = unknown>(table: string, data: Record<string, unknown>): Promise<T> {
+    const { sql, params } = compileInsert(table, data);
+    const rows = await this.query<T>(sql, params);
+    if (!rows || rows.length === 0) {
+      throw new Error(`Failed to insert into ${table}: no row returned`);
+    }
+    return rows[0];
+  }
+
+  async update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition): Promise<T[]> {
+    const { sql, params } = compileUpdate(table, data, where);
+    return this.query<T>(sql, params);
+  }
+
+  async delete(table: string, where: WhereCondition): Promise<number> {
+    const { sql, params } = compileDelete(table, where);
+    const rows = await this.query(sql, params);
+    return rows.length;
+  }
+
+  async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
+    const res = await this.client.begin(async (sqlTx) => {
+      const txClient: DatabaseClient = {
+        query: async <U = unknown>(q: string, p: unknown[] = []) => {
+          const res = await sqlTx.unsafe(q, p as any[]);
+          return res as unknown as U[];
+        },
+        queryOne: async <U = unknown>(q: string, p: unknown[] = []) => {
+          const res = await sqlTx.unsafe(q, p as any[]);
+          return (res[0] ?? null) as U | null;
+        },
+        sql: async <U = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => {
+          const { text, params } = compileTaggedSql(strings, ...values);
+          const res = await sqlTx.unsafe(text, params as any[]);
+          return res as unknown as U[];
+        },
+        sqlOne: async <U = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => {
+          const { text, params } = compileTaggedSql(strings, ...values);
+          const res = await sqlTx.unsafe(text, params as any[]);
+          return (res[0] ?? null) as U | null;
+        },
+        findMany: async <U = unknown>(table: string, options?: QueryOptions) => {
+          const { sql, params } = compileSelect(table, options);
+          const rows = await txClient.query<Record<string, unknown>>(sql, params);
+          if (options?.join && options.join.length > 0) {
+            return rows.map((r) => nestJoinedRow<U>(r, options.join));
+          }
+          return rows as unknown as U[];
+        },
+        findOne: async <U = unknown>(table: string, options?: QueryOptions) => {
+          const opts = { ...options, limit: 1 };
+          const { sql, params } = compileSelect(table, opts);
+          const row = await txClient.queryOne<Record<string, unknown>>(sql, params);
+          if (!row) return null;
+          if (options?.join && options.join.length > 0) {
+            return nestJoinedRow<U>(row, options.join);
+          }
+          return row as unknown as U;
+        },
+        insert: async <U = unknown>(table: string, data: Record<string, unknown>) => {
+          const { sql, params } = compileInsert(table, data);
+          const rows = await txClient.query<U>(sql, params);
+          if (!rows || rows.length === 0) {
+            throw new Error(`Failed to insert into ${table}: no row returned`);
+          }
+          return rows[0];
+        },
+        update: async <U = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition) => {
+          const { sql, params } = compileUpdate(table, data, where);
+          return txClient.query<U>(sql, params);
+        },
+        delete: async (table: string, where: WhereCondition) => {
+          const { sql, params } = compileDelete(table, where);
+          const rows = await txClient.query(sql, params);
+          return rows.length;
+        },
+        transaction: async <U>(subOp: (nestedTx: DatabaseClient) => Promise<U>) => {
+          return await subOp(txClient);
+        }
+      };
+      return await operation(txClient);
+    });
+    return res as T;
+  }
+
+  async close(): Promise<void> {
+    await this.client.end();
+  }
+}

package/src/core/postgres-queue.ts

@@ -0,0 +1,288 @@
+/**
+ * SynapseJS - Distributed PostgreSQL Queue Engine
+ *
+ * Provides cluster-safe background job processing with zero row collisions across multiple worker nodes,
+ * using PostgreSQL's native `FOR UPDATE SKIP LOCKED`, visibility timeouts for crash recovery,
+ * exponential backoff with Full Jitter, and dedicated Dead Letter Queue (DLQ).
+ */
+
+import type { JobRecord } from '../runtime/queue-engine';
+import type { DatabaseClient } from './database-client';
+import {
+  AnonymousSession,
+  createActionContext,
+  createDefaultLogger,
+  type JobDefinition,
+  type JobEnqueueOptions,
+  type SessionContext,
+  type StructuredLogger
+} from './index';
+
+export interface PostgresQueueOptions {
+  db: DatabaseClient;
+  logger?: StructuredLogger;
+  visibilityTimeoutSeconds?: number;
+}
+
+export interface DlqRecord {
+  id: string;
+  job_id: string;
+  name: string;
+  payload: string;
+  attempts: number;
+  max_attempts: number;
+  last_error: string | null;
+  failed_at: number;
+}
+
+export class PostgresQueueEngine {
+  private db: DatabaseClient;
+  private logger: StructuredLogger;
+  private visibilityTimeoutMs: number;
+  private registry: Map<string, JobDefinition<unknown>> = new Map();
+  private schemaInitialized = false;
+
+  constructor(options: PostgresQueueOptions) {
+    this.db = options.db;
+    this.logger = options.logger || createDefaultLogger('PostgresQueue');
+    this.visibilityTimeoutMs = (options.visibilityTimeoutSeconds ?? 300) * 1000;
+  }
+
+  async initSchema(): Promise<void> {
+    if (this.schemaInitialized) return;
+
+    await this.db.query(`
+      CREATE TABLE IF NOT EXISTS _synapse_jobs (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        status TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        max_attempts INTEGER NOT NULL DEFAULT 3,
+        backoff_seconds INTEGER NOT NULL DEFAULT 5,
+        run_at BIGINT NOT NULL,
+        locked_at BIGINT,
+        created_at BIGINT NOT NULL,
+        updated_at BIGINT NOT NULL,
+        last_error TEXT
+      );
+    `);
+
+    await this.db.query(`
+      CREATE TABLE IF NOT EXISTS _synapse_jobs_dlq (
+        id TEXT PRIMARY KEY,
+        job_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        attempts INTEGER NOT NULL,
+        max_attempts INTEGER NOT NULL,
+        last_error TEXT,
+        failed_at BIGINT NOT NULL
+      );
+    `);
+
+    await this.db.query(`
+      CREATE INDEX IF NOT EXISTS idx_synapse_jobs_pending 
+      ON _synapse_jobs (status, run_at, priority DESC);
+    `);
+
+    await this.db.query(`
+      CREATE INDEX IF NOT EXISTS idx_synapse_jobs_stale
+      ON _synapse_jobs (status, locked_at);
+    `);
+
+    this.schemaInitialized = true;
+  }
+
+  registerJob<T>(job: JobDefinition<T>): void {
+    this.registry.set(job.name, job as JobDefinition<unknown>);
+  }
+
+  async enqueue<TPayload>(
+    jobOrName: { name: string; retryLimit?: number; backoffSeconds?: number } | string,
+    payload: TPayload,
+    options?: JobEnqueueOptions
+  ): Promise<string> {
+    await this.initSchema();
+
+    const id = `job_${crypto.randomUUID().replace(/-/g, '')}`;
+    const name = typeof jobOrName === 'string' ? jobOrName : jobOrName.name;
+    const maxAttempts = typeof jobOrName === 'object' && jobOrName.retryLimit ? jobOrName.retryLimit : 3;
+    const backoffSeconds = typeof jobOrName === 'object' && jobOrName.backoffSeconds ? jobOrName.backoffSeconds : 5;
+    const priority = options?.priority ?? 0;
+    const delaySeconds = options?.delaySeconds ?? 0;
+    const now = Date.now();
+    const runAt = now + delaySeconds * 1000;
+    const payloadStr = JSON.stringify(payload);
+
+    await this.db.query(
+      `INSERT INTO _synapse_jobs (
+        id, name, payload, status, priority, attempts, max_attempts, backoff_seconds, run_at, locked_at, created_at, updated_at
+      ) VALUES ($1, $2, $3, 'pending', $4, 0, $5, $6, $7, NULL, $8, $8)`,
+      [id, name, payloadStr, priority, maxAttempts, backoffSeconds, runAt, now]
+    );
+
+    return id;
+  }
+
+  /**
+   * Atomically claims the next pending job or recovers orphaned jobs whose worker died
+   * (locked_at older than visibilityTimeout), using PostgreSQL's FOR UPDATE SKIP LOCKED.
+   */
+  async claimNextJob(): Promise<JobRecord | null> {
+    await this.initSchema();
+
+    const now = Date.now();
+    const staleThreshold = now - this.visibilityTimeoutMs;
+
+    const rows = await this.db.query<JobRecord>(
+      `UPDATE _synapse_jobs
+       SET status = 'running', locked_at = $1, updated_at = $1
+       WHERE id = (
+         SELECT id FROM _synapse_jobs
+         WHERE (status = 'pending' AND run_at <= $1)
+            OR (status = 'running' AND locked_at < $2)
+         ORDER BY priority DESC, run_at ASC, created_at ASC
+         LIMIT 1
+         FOR UPDATE SKIP LOCKED
+       )
+       RETURNING *;`,
+      [now, staleThreshold]
+    );
+
+    return rows.length > 0 ? rows[0] : null;
+  }
+
+  /**
+   * Processes a single claimed job.
+   */
+  async processNextJob(deps: {
+    db: DatabaseClient;
+    session?: SessionContext;
+    services?: Record<string, unknown>;
+    logger?: StructuredLogger;
+  }): Promise<boolean> {
+    const job = await this.claimNextJob();
+    if (!job) {
+      return false;
+    }
+
+    const jobDef = this.registry.get(job.name);
+    const attempts = Number(job.attempts) + 1;
+    const now = Date.now();
+
+    if (!jobDef) {
+      const errorMsg = `Nenhum manipulador registrado para o job: ${job.name}`;
+      this.logger.error(errorMsg);
+      await this.sendToDlq(job, attempts, errorMsg, now);
+      return true;
+    }
+
+    let parsedPayload: unknown;
+    try {
+      parsedPayload = JSON.parse(job.payload);
+    } catch (parseErr: unknown) {
+      const errorMsg = `Falha ao desserializar payload JSON do job: ${String(parseErr)}`;
+      await this.sendToDlq(job, attempts, errorMsg, now);
+      return true;
+    }
+
+    const actionCtx = createActionContext({
+      db: deps.db,
+      session: deps.session || AnonymousSession(),
+      services: deps.services || {},
+      logger: deps.logger || this.logger,
+      enqueue: this.enqueue.bind(this)
+    });
+
+    try {
+      await jobDef.handler(parsedPayload, actionCtx);
+      await this.db.query(
+        `UPDATE _synapse_jobs
+         SET status = 'completed', attempts = $1, locked_at = NULL, updated_at = $2, last_error = NULL
+         WHERE id = $3`,
+        [attempts, now, job.id]
+      );
+      return true;
+    } catch (handlerErr: unknown) {
+      const errorMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
+      this.logger.warn(`Job ${job.name} (${job.id}) falhou na tentativa ${attempts}/${job.max_attempts}: ${errorMsg}`);
+
+      if (attempts < Number(job.max_attempts)) {
+        // AWS Full Jitter: distributes retries uniformly in [0, baseBackoff] to prevent thundering herd
+        const baseBackoffMs = Number(job.backoff_seconds) * 1000 * 2 ** (attempts - 1);
+        const jitteredBackoffMs = Math.floor(Math.random() * baseBackoffMs);
+        const nextRunAt = now + jitteredBackoffMs;
+
+        await this.db.query(
+          `UPDATE _synapse_jobs
+           SET status = 'pending', attempts = $1, run_at = $2, locked_at = NULL, updated_at = $3, last_error = $4
+           WHERE id = $5`,
+          [attempts, nextRunAt, now, errorMsg, job.id]
+        );
+      } else {
+        await this.sendToDlq(job, attempts, `Esgotado limite de tentativas (${job.max_attempts}): ${errorMsg}`, now);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Routes exhausted or permanently failed jobs to the Dead Letter Queue (DLQ).
+   */
+  private async sendToDlq(job: JobRecord, attempts: number, errorMsg: string, now: number): Promise<string> {
+    const dlqId = `dlq_${crypto.randomUUID().replace(/-/g, '')}`;
+
+    await this.db.query(
+      `INSERT INTO _synapse_jobs_dlq (
+        id, job_id, name, payload, attempts, max_attempts, last_error, failed_at
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+      [dlqId, job.id, job.name, job.payload, attempts, Number(job.max_attempts), errorMsg, now]
+    );
+
+    await this.db.query(
+      `UPDATE _synapse_jobs
+       SET status = 'dlq', attempts = $1, locked_at = NULL, updated_at = $2, last_error = $3
+       WHERE id = $4`,
+      [attempts, now, errorMsg, job.id]
+    );
+
+    this.logger.warn(`[DLQ] Job ${job.name} (${job.id}) movido para Dead Letter Queue: ${dlqId}`);
+    return dlqId;
+  }
+
+  /**
+   * Inspects records currently sitting in the Dead Letter Queue.
+   */
+  async getDlqJobs(limit = 50): Promise<DlqRecord[]> {
+    await this.initSchema();
+    return this.db.query<DlqRecord>(`SELECT * FROM _synapse_jobs_dlq ORDER BY failed_at DESC LIMIT $1`, [limit]);
+  }
+
+  /**
+   * Retries a job from the DLQ by restoring it to pending status with attempts reset.
+   */
+  async retryDlqJob(dlqId: string): Promise<boolean> {
+    await this.initSchema();
+    const rows = await this.db.query<DlqRecord>(`SELECT * FROM _synapse_jobs_dlq WHERE id = $1`, [dlqId]);
+
+    if (rows.length === 0) return false;
+    const dlq = rows[0];
+    const now = Date.now();
+
+    await this.db.query(
+      `UPDATE _synapse_jobs
+       SET status = 'pending', attempts = 0, run_at = $1, locked_at = NULL, updated_at = $1, last_error = NULL
+       WHERE id = $2`,
+      [now, dlq.job_id]
+    );
+
+    await this.db.query(`DELETE FROM _synapse_jobs_dlq WHERE id = $1`, [dlqId]);
+    return true;
+  }
+
+  async close(): Promise<void> {
+    // No-op for db instance managed externally
+  }
+}