Skip to main content

ReTraced – Technical Model & Schemas

This document describes the core data models that power ReTraced’s explicit retry, failure, and DLQ semantics.

All retry behavior is driven by data, not hidden state machines.

Job Model​

A Job represents a unit of work in the system.

Job Lifecycle States​

Job Schema​

export type Job = {
  jobId: string;

  createdAt: number;
  updatedAt?: number;

  jobData: JobData;

  queueName: string;

  status:
    | 'pending'
    | 'processing'
    | 'completed'
    | 'failed'
    | 'dead'
    | 'delayed'
    | 'poisoned';

  tries: number;
  maxTries: number;
  
  lastError?: JobError;


  type?: string;
  priority?: number;
  runAt?: number;
  
  historyNeed: boolean;
  history?: History[];

  backoffConfig: BackoffConfig;
  backoffStrategy?: 'exponential' | 'fixed' | 'threeTier' | 'linear';
}

History Model​

Each retry attempt is explicitly recorded.

export type History = {
  error: JobError;
  attemptedAt: number;
  trigger: 'AUTO' | 'MANUAL';
  changesMade: boolean;
  result: 'SUCCESS' | 'FAILED' | 'PENDING';
};

Why This Matters​

  • Retries are auditable
  • Manual vs automatic retries are distinguishable
  • Retry intent is preserved

Error Model​

export type JobError = {
  code: JobErrorCode;
  message: string;
  stack?: string;
  failedAt: number;
};

Errors are treated as structured data, enabling:

  • Failure classification
  • Root-cause analysis
  • Consistent DLQ forensics

Backoff Configuration​

export type BackoffConfig = {
  baseDelaySeconds: number;
  maxDelaySeconds: number;
  factor: number;
  jitterSeconds?: number;
  limitOfTries: number;
};

This config allows

  • Fine-grained retry tuning
  • Strategy-agnostic retry calculation
  • Safe scaling under failure

Dead Letter Queue (DLQ) Model​

DLQ entries are not failed jobs — they are preserved execution artifacts.

export type dlq = {
  jobId: string;
  queueName: string;

  jobData: unknown;

  status: 'dead' | 'poisoned';

  failureType?: 'TEMPORARY' | 'PERMANENT' | 'POISON';

  maxTries: number;
  tries: number;

  lastError: JobError;

  retries?: DLQRetryAttempt[];

  createdAt: number;
  updatedAt?: number;

  deadReason?: string;

  priority?: number;
  runAt?: number;

  backoffConfig: BackoffConfig;
  backoffStrategy?: 'exponential' | 'fixed' | 'threeTier' | 'linear';
};

DLQ Retry Attempt Model​

Retries from DLQ are tracked separately and explicitly.

export type DLQRetryAttempt = {
  attemptedAt: number;
  trigger: 'MANUAL' | 'AUTO';
  changesMade: boolean;
  changesInJob?: string;
  result: 'FAILED' | 'SUCCESS';
  error?: JobError;
};

Key Properties​

  • Manual intervention is visible
  • Changes are documented
  • Poison jobs are identifiable
  • Design Guarantees
  • At-least-once delivery
  • Explicit retry tracking
  • Deterministic state transitions
  • DLQ as a permanent forensic record

Technical Summary​

ReTraced’s architecture is driven by explicit schemas, not implicit behavior.

Every retry, failure, and decision is:

  • Recorded
  • Inspectable
  • Replayable

This makes ReTraced ideal for systems where understanding execution behavior matters as much as execution itself.