duron 0.3.0-beta.8 → 0.3.0

package/dist/adapters/postgres/base.js

@@ -8,6 +8,14 @@ export class PostgresBaseAdapter extends Adapter {
     tables;
     schema = 'duron';
     migrateOnStart = true;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new PostgresAdapter instance.
+     *
+     * @param options - Configuration options for the PostgreSQL adapter
+     */
     constructor(options) {
         super();
         this.connection = options.connection;
@@ -16,9 +24,21 @@ export class PostgresBaseAdapter extends Adapter {
         this.tables = createSchema(this.schema);
         this._initDb();
     }
+    /**
+     * Initialize the database connection and Drizzle instance.
+     */
     _initDb() {
         throw new Error('Not implemented');
     }
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Start the adapter.
+     * Runs migrations if enabled and sets up database listeners.
+     *
+     * @returns Promise resolving to `true` if started successfully, `false` otherwise
+     */
     async _start() {
         await this._listen(`ping-${this.id}`, async (payload) => {
             const fromClientId = JSON.parse(payload).fromClientId;
@@ -38,18 +58,29 @@ export class PostgresBaseAdapter extends Adapter {
         });
     }
     async _stop() {
+        // do nothing
     }
-    async _createJob({ queue, groupKey, input, timeoutMs, checksum, concurrencyLimit }) {
+    // ============================================================================
+    // Job Methods
+    // ============================================================================
+    /**
+     * Internal method to create a new job in the database.
+     *
+     * @returns Promise resolving to the job ID, or `null` if creation failed
+     */
+    async _createJob({ queue, groupKey, input, timeoutMs, checksum, concurrencyLimit, concurrencyStepLimit, description, }) {
         const [result] = await this.db
             .insert(this.tables.jobsTable)
             .values({
             action_name: queue,
             group_key: groupKey,
+            description: description ?? null,
             checksum,
             input,
             status: JOB_STATUS_CREATED,
             timeout_ms: timeoutMs,
             concurrency_limit: concurrencyLimit,
+            concurrency_step_limit: concurrencyStepLimit,
         })
             .returning({ id: this.tables.jobsTable.id });
         if (!result) {
@@ -57,6 +88,11 @@ export class PostgresBaseAdapter extends Adapter {
         }
         return result.id;
     }
+    /**
+     * Internal method to mark a job as completed.
+     *
+     * @returns Promise resolving to `true` if completed, `false` otherwise
+     */
     async _completeJob({ jobId, output }) {
         const result = await this.db
             .update(this.tables.jobsTable)
@@ -70,6 +106,11 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to mark a job as failed.
+     *
+     * @returns Promise resolving to `true` if failed, `false` otherwise
+     */
     async _failJob({ jobId, error }) {
         const result = await this.db
             .update(this.tables.jobsTable)
@@ -83,6 +124,11 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to cancel a job.
+     *
+     * @returns Promise resolving to `true` if cancelled, `false` otherwise
+     */
     async _cancelJob({ jobId }) {
         const result = await this.db
             .update(this.tables.jobsTable)
@@ -95,18 +141,27 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to retry a completed, cancelled, or failed job by creating a copy of it with status 'created' and cleared output/error.
+     * Uses SELECT FOR UPDATE to prevent concurrent retries from creating duplicate jobs.
+     *
+     * @returns Promise resolving to the job ID, or `null` if creation failed
+     */
     async _retryJob({ jobId }) {
+        // Use a single atomic query with FOR UPDATE lock to prevent race conditions
         const result = this._map(await this.db.execute(sql `
       WITH locked_source AS (
         -- Lock the source job row to prevent concurrent retries
         SELECT
           j.action_name,
           j.group_key,
+          j.description,
           j.checksum,
           j.input,
           j.timeout_ms,
           j.created_at,
-          j.concurrency_limit
+          j.concurrency_limit,
+          j.concurrency_step_limit
         FROM ${this.tables.jobsTable} j
         WHERE j.id = ${jobId}
           AND j.status IN (${JOB_STATUS_COMPLETED}, ${JOB_STATUS_CANCELLED}, ${JOB_STATUS_FAILED})
@@ -131,15 +186,18 @@ export class PostgresBaseAdapter extends Adapter {
         INSERT INTO ${this.tables.jobsTable} (
           action_name,
           group_key,
+          description,
           checksum,
           input,
           status,
           timeout_ms,
-          concurrency_limit
+          concurrency_limit,
+          concurrency_step_limit
         )
         SELECT
           ls.action_name,
           ls.group_key,
+          ls.description,
           ls.checksum,
           ls.input,
           ${JOB_STATUS_CREATED},
@@ -155,7 +213,8 @@ export class PostgresBaseAdapter extends Adapter {
               LIMIT 1
             ),
             ls.concurrency_limit
-          )
+          ),
+          ls.concurrency_step_limit
         FROM locked_source ls
         WHERE NOT EXISTS (SELECT 1 FROM existing_retry)
         RETURNING id
@@ -169,6 +228,25 @@ export class PostgresBaseAdapter extends Adapter {
         }
         return result[0].id;
     }
+    /**
+     * Internal method to time travel a job to restart from a specific step.
+     * The job must be in completed, failed, or cancelled status.
+     * Resets the job and ancestor steps to active status, deletes subsequent steps,
+     * and preserves completed parallel siblings.
+     *
+     * Algorithm:
+     * 1. Validate job is in terminal state (completed/failed/cancelled)
+     * 2. Find the target step and all its ancestors (using parent_step_id)
+     * 3. Determine which steps to keep:
+     *    - Steps completed BEFORE the target step (by created_at)
+     *    - Branch siblings that are completed (independent)
+     * 4. Delete steps that should not be kept
+     * 5. Reset ancestor steps to active status (they need to re-run)
+     * 6. Reset the target step to active status
+     * 7. Reset job to created status
+     *
+     * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+     */
     async _timeTravelJob({ jobId, stepId }) {
         const result = this._map(await this.db.execute(sql `
       WITH RECURSIVE
@@ -336,16 +414,29 @@ export class PostgresBaseAdapter extends Adapter {
     `));
         return result.length > 0 && result[0].success === true;
     }
+    /**
+     * Internal method to delete a job by its ID.
+     * Active jobs cannot be deleted.
+     *
+     * @returns Promise resolving to `true` if deleted, `false` otherwise
+     */
     async _deleteJob({ jobId }) {
         const result = await this.db
             .delete(this.tables.jobsTable)
             .where(and(eq(this.tables.jobsTable.id, jobId), ne(this.tables.jobsTable.status, JOB_STATUS_ACTIVE)))
             .returning({ id: this.tables.jobsTable.id });
+        // Also delete associated steps
         if (result.length > 0) {
             await this.db.delete(this.tables.jobStepsTable).where(eq(this.tables.jobStepsTable.job_id, jobId));
         }
         return result.length > 0;
     }
+    /**
+     * Internal method to delete multiple jobs using the same filters as getJobs.
+     * Active jobs cannot be deleted and will be excluded from deletion.
+     *
+     * @returns Promise resolving to the number of jobs deleted
+     */
     async _deleteJobs(options) {
         const jobsTable = this.tables.jobsTable;
         const filters = options?.filters ?? {};
@@ -353,6 +444,13 @@ export class PostgresBaseAdapter extends Adapter {
         const result = await this.db.delete(jobsTable).where(where).returning({ id: jobsTable.id });
         return result.length;
     }
+    /**
+     * Internal method to fetch jobs from the database respecting concurrency limits per group.
+     * Uses the concurrency limit from the latest job created for each groupKey.
+     * Uses advisory locks to ensure thread-safe job fetching.
+     *
+     * @returns Promise resolving to an array of fetched jobs
+     */
     async _fetch({ batch }) {
         const result = this._map(await this.db.execute(sql `
       WITH group_concurrency AS (
@@ -450,6 +548,7 @@ export class PostgresBaseAdapter extends Adapter {
         j.id,
         j.action_name as "actionName",
         j.group_key as "groupKey",
+        j.description,
         j.input,
         j.output,
         j.error,
@@ -460,10 +559,17 @@ export class PostgresBaseAdapter extends Adapter {
         j.finished_at as "finishedAt",
         j.created_at as "createdAt",
         j.updated_at as "updatedAt",
-        j.concurrency_limit as "concurrencyLimit"
+        j.concurrency_limit as "concurrencyLimit",
+        j.concurrency_step_limit as "concurrencyStepLimit"
     `));
         return result;
     }
+    /**
+     * Internal method to recover stuck jobs (jobs that were active but the process that owned them is no longer running).
+     * In multi-process mode, pings other processes to check if they're alive before recovering their jobs.
+     *
+     * @returns Promise resolving to the number of jobs recovered
+     */
     async _recoverJobs(options) {
         const { checksums, multiProcessMode = false, processTimeout = 5_000 } = options;
         const unresponsiveClientIds = [this.id];
@@ -527,6 +633,14 @@ export class PostgresBaseAdapter extends Adapter {
         }
         return 0;
     }
+    // ============================================================================
+    // Step Methods
+    // ============================================================================
+    /**
+     * Internal method to create or recover a job step by creating or resetting a step record in the database.
+     *
+     * @returns Promise resolving to the step, or `null` if creation failed
+     */
     async _createOrRecoverJobStep({ jobId, name, timeoutMs, retriesLimit, parentStepId, parallel = false, }) {
         const [result] = this._map(await this.db.execute(sql `
       WITH job_check AS (
@@ -539,7 +653,7 @@ export class PostgresBaseAdapter extends Adapter {
       step_existed AS (
         SELECT EXISTS(
           SELECT 1 FROM ${this.tables.jobStepsTable} s
-          WHERE s.job_id = ${jobId} 
+          WHERE s.job_id = ${jobId}
             AND s.name = ${name}
             AND s.parent_step_id IS NOT DISTINCT FROM ${parentStepId}
         ) AS existed
@@ -624,6 +738,11 @@ export class PostgresBaseAdapter extends Adapter {
         }
         return result;
     }
+    /**
+     * Internal method to mark a job step as completed.
+     *
+     * @returns Promise resolving to `true` if completed, `false` otherwise
+     */
     async _completeJobStep({ stepId, output }) {
         const result = await this.db
             .update(this.tables.jobStepsTable)
@@ -638,6 +757,11 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobStepsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to mark a job step as failed.
+     *
+     * @returns Promise resolving to `true` if failed, `false` otherwise
+     */
     async _failJobStep({ stepId, error }) {
         const result = await this.db
             .update(this.tables.jobStepsTable)
@@ -652,6 +776,11 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobStepsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to delay a job step.
+     *
+     * @returns Promise resolving to `true` if delayed, `false` otherwise
+     */
     async _delayJobStep({ stepId, delayMs, error }) {
         const jobStepsTable = this.tables.jobStepsTable;
         const jobsTable = this.tables.jobsTable;
@@ -676,6 +805,11 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: jobStepsTable.id });
         return result.length > 0;
     }
+    /**
+     * Internal method to cancel a job step.
+     *
+     * @returns Promise resolving to `true` if cancelled, `false` otherwise
+     */
     async _cancelJobStep({ stepId }) {
         const result = await this.db
             .update(this.tables.jobStepsTable)
@@ -689,30 +823,53 @@ export class PostgresBaseAdapter extends Adapter {
             .returning({ id: this.tables.jobStepsTable.id });
         return result.length > 0;
     }
+    // ============================================================================
+    // Query Methods
+    // ============================================================================
+    /**
+     * Internal method to get a job by its ID. Does not include step information.
+     */
     async _getJobById(jobId) {
+        const jobsTable = this.tables.jobsTable;
+        // Calculate duration as a SQL expression (finishedAt - startedAt in milliseconds)
+        const durationMs = sql `
+      CASE
+        WHEN ${jobsTable.started_at} IS NOT NULL AND ${jobsTable.finished_at} IS NOT NULL
+        THEN EXTRACT(EPOCH FROM (${jobsTable.finished_at} - ${jobsTable.started_at})) * 1000
+        ELSE NULL
+      END
+    `.as('duration_ms');
         const [job] = await this.db
             .select({
-            id: this.tables.jobsTable.id,
-            actionName: this.tables.jobsTable.action_name,
-            groupKey: this.tables.jobsTable.group_key,
-            input: this.tables.jobsTable.input,
-            output: this.tables.jobsTable.output,
-            error: this.tables.jobsTable.error,
-            status: this.tables.jobsTable.status,
-            timeoutMs: this.tables.jobsTable.timeout_ms,
-            expiresAt: this.tables.jobsTable.expires_at,
-            startedAt: this.tables.jobsTable.started_at,
-            finishedAt: this.tables.jobsTable.finished_at,
-            createdAt: this.tables.jobsTable.created_at,
-            updatedAt: this.tables.jobsTable.updated_at,
-            concurrencyLimit: this.tables.jobsTable.concurrency_limit,
-            clientId: this.tables.jobsTable.client_id,
+            id: jobsTable.id,
+            actionName: jobsTable.action_name,
+            groupKey: jobsTable.group_key,
+            description: jobsTable.description,
+            input: jobsTable.input,
+            output: jobsTable.output,
+            error: jobsTable.error,
+            status: jobsTable.status,
+            timeoutMs: jobsTable.timeout_ms,
+            expiresAt: jobsTable.expires_at,
+            startedAt: jobsTable.started_at,
+            finishedAt: jobsTable.finished_at,
+            createdAt: jobsTable.created_at,
+            updatedAt: jobsTable.updated_at,
+            concurrencyLimit: jobsTable.concurrency_limit,
+            concurrencyStepLimit: jobsTable.concurrency_step_limit,
+            clientId: jobsTable.client_id,
+            durationMs,
         })
-            .from(this.tables.jobsTable)
-            .where(eq(this.tables.jobsTable.id, jobId))
+            .from(jobsTable)
+            .where(eq(jobsTable.id, jobId))
             .limit(1);
         return job ?? null;
     }
+    /**
+     * Internal method to get all steps for a job with optional fuzzy search.
+     * Steps are always ordered by created_at ASC.
+     * Steps do not include output data.
+     */
     async _getJobSteps(options) {
         const { jobId, search } = options;
         const jobStepsTable = this.tables.jobStepsTable;
@@ -756,6 +913,7 @@ export class PostgresBaseAdapter extends Adapter {
         }
         const jobsTable = this.tables.jobsTable;
         const fuzzySearch = filters.search?.trim();
+        // Build WHERE clause parts using postgres template literals
         return and(filters.status
             ? inArray(jobsTable.status, Array.isArray(filters.status) ? filters.status : [filters.status])
             : undefined, filters.actionName
@@ -766,7 +924,7 @@ export class PostgresBaseAdapter extends Adapter {
             ? ilike(jobsTable.group_key, `%${filters.groupKey}%`)
             : undefined, filters.clientId
             ? inArray(jobsTable.client_id, Array.isArray(filters.clientId) ? filters.clientId : [filters.clientId])
-            : undefined, filters.createdAt && Array.isArray(filters.createdAt)
+            : undefined, filters.description ? ilike(jobsTable.description, `%${filters.description}%`) : undefined, filters.createdAt && Array.isArray(filters.createdAt)
             ? between(sql `date_trunc('second', ${jobsTable.created_at})`, filters.createdAt[0].toISOString(), filters.createdAt[1].toISOString())
             : undefined, filters.createdAt && !Array.isArray(filters.createdAt)
             ? gte(sql `date_trunc('second', ${jobsTable.created_at})`, filters.createdAt.toISOString())
@@ -781,13 +939,17 @@ export class PostgresBaseAdapter extends Adapter {
             : undefined, filters.updatedAfter
             ? sql `date_trunc('milliseconds', ${jobsTable.updated_at}) > ${filters.updatedAfter.toISOString()}::timestamptz`
             : undefined, fuzzySearch && fuzzySearch.length > 0
-            ? or(ilike(jobsTable.action_name, `%${fuzzySearch}%`), ilike(jobsTable.group_key, `%${fuzzySearch}%`), ilike(jobsTable.client_id, `%${fuzzySearch}%`), sql `${jobsTable.id}::text ilike ${`%${fuzzySearch}%`}`, sql `to_tsvector('english', ${jobsTable.input}::text) @@ plainto_tsquery('english', ${fuzzySearch})`, sql `to_tsvector('english', ${jobsTable.output}::text) @@ plainto_tsquery('english', ${fuzzySearch})`)
+            ? or(ilike(jobsTable.action_name, `%${fuzzySearch}%`), ilike(jobsTable.group_key, `%${fuzzySearch}%`), ilike(jobsTable.description, `%${fuzzySearch}%`), ilike(jobsTable.client_id, `%${fuzzySearch}%`), sql `${jobsTable.id}::text ilike ${`%${fuzzySearch}%`}`, sql `to_tsvector('english', ${jobsTable.input}::text) @@ plainto_tsquery('english', ${fuzzySearch})`, sql `to_tsvector('english', ${jobsTable.output}::text) @@ plainto_tsquery('english', ${fuzzySearch})`)
             : undefined, ...(filters.inputFilter && Object.keys(filters.inputFilter).length > 0
             ? this.#buildJsonbWhereConditions(filters.inputFilter, jobsTable.input)
             : []), ...(filters.outputFilter && Object.keys(filters.outputFilter).length > 0
             ? this.#buildJsonbWhereConditions(filters.outputFilter, jobsTable.output)
             : []));
     }
+    /**
+     * Internal method to get jobs with pagination, filtering, and sorting.
+     * Does not include step information or job output.
+     */
     async _getJobs(options) {
         const jobsTable = this.tables.jobsTable;
         const page = options?.page ?? 1;
@@ -796,6 +958,7 @@ export class PostgresBaseAdapter extends Adapter {
         const sortInput = options?.sort ?? { field: 'startedAt', order: 'desc' };
         const sorts = Array.isArray(sortInput) ? sortInput : [sortInput];
         const where = this._buildJobsWhereClause(filters);
+        // Get total count
         const total = await this.db.$count(jobsTable, where);
         if (!total) {
             return {
@@ -805,6 +968,14 @@ export class PostgresBaseAdapter extends Adapter {
                 pageSize,
             };
         }
+        // Calculate duration as a SQL expression (finishedAt - startedAt in milliseconds)
+        const durationMs = sql `
+      CASE
+        WHEN ${jobsTable.started_at} IS NOT NULL AND ${jobsTable.finished_at} IS NOT NULL
+        THEN EXTRACT(EPOCH FROM (${jobsTable.finished_at} - ${jobsTable.started_at})) * 1000
+        ELSE NULL
+      END
+    `.as('duration_ms');
         const sortFieldMap = {
             createdAt: jobsTable.created_at,
             startedAt: jobsTable.started_at,
@@ -812,12 +983,15 @@ export class PostgresBaseAdapter extends Adapter {
             status: jobsTable.status,
             actionName: jobsTable.action_name,
             expiresAt: jobsTable.expires_at,
+            duration: durationMs,
+            description: jobsTable.description,
         };
         const jobs = await this.db
             .select({
             id: jobsTable.id,
             actionName: jobsTable.action_name,
             groupKey: jobsTable.group_key,
+            description: jobsTable.description,
             input: jobsTable.input,
             output: jobsTable.output,
             error: jobsTable.error,
@@ -829,7 +1003,9 @@ export class PostgresBaseAdapter extends Adapter {
             createdAt: jobsTable.created_at,
             updatedAt: jobsTable.updated_at,
             concurrencyLimit: jobsTable.concurrency_limit,
+            concurrencyStepLimit: jobsTable.concurrency_step_limit,
             clientId: jobsTable.client_id,
+            durationMs,
         })
             .from(jobsTable)
             .where(where)
@@ -853,6 +1029,9 @@ export class PostgresBaseAdapter extends Adapter {
             pageSize,
         };
     }
+    /**
+     * Internal method to get a step by its ID with all information.
+     */
     async _getJobStepById(stepId) {
         const [step] = await this.db
             .select({
@@ -880,6 +1059,9 @@ export class PostgresBaseAdapter extends Adapter {
             .limit(1);
         return step ?? null;
     }
+    /**
+     * Internal method to get job status and updatedAt timestamp.
+     */
     async _getJobStatus(jobId) {
         const [job] = await this.db
             .select({
@@ -891,6 +1073,9 @@ export class PostgresBaseAdapter extends Adapter {
             .limit(1);
         return job ?? null;
     }
+    /**
+     * Internal method to get job step status and updatedAt timestamp.
+     */
     async _getJobStepStatus(stepId) {
         const [step] = await this.db
             .select({
@@ -902,6 +1087,9 @@ export class PostgresBaseAdapter extends Adapter {
             .limit(1);
         return step ?? null;
     }
+    /**
+     * Internal method to get action statistics including counts and last job created date.
+     */
     async _getActions() {
         const actionStats = this.db.$with('action_stats').as(this.db
             .select({
@@ -933,85 +1121,217 @@ export class PostgresBaseAdapter extends Adapter {
             })),
         };
     }
-    async _insertMetrics(metrics) {
-        if (metrics.length === 0) {
+    // ============================================================================
+    // Metrics Methods
+    // ============================================================================
+    /**
+     * Internal method to insert multiple span records in a single batch.
+     */
+    async _insertSpans(spans) {
+        if (spans.length === 0) {
             return 0;
         }
-        const values = metrics.map((m) => ({
-            job_id: m.jobId,
-            step_id: m.stepId ?? null,
-            name: m.name,
-            value: m.value,
-            attributes: m.attributes ?? {},
-            type: m.type,
+        const values = spans.map((s) => ({
+            trace_id: s.traceId,
+            span_id: s.spanId,
+            parent_span_id: s.parentSpanId,
+            job_id: s.jobId,
+            step_id: s.stepId,
+            name: s.name,
+            kind: s.kind,
+            start_time_unix_nano: s.startTimeUnixNano,
+            end_time_unix_nano: s.endTimeUnixNano,
+            status_code: s.statusCode,
+            status_message: s.statusMessage,
+            attributes: s.attributes ?? {},
+            events: s.events ?? [],
         }));
         const result = await this.db
-            .insert(this.tables.metricsTable)
+            .insert(this.tables.spansTable)
             .values(values)
-            .returning({ id: this.tables.metricsTable.id });
+            .returning({ id: this.tables.spansTable.id });
         return result.length;
     }
-    async _getMetrics(options) {
-        const metricsTable = this.tables.metricsTable;
+    /**
+     * Internal method to get spans for a job or step.
+     * For step queries, uses a recursive CTE to find all descendant spans.
+     */
+    async _getSpans(options) {
+        const spansTable = this.tables.spansTable;
         const filters = options.filters ?? {};
-        const where = this._buildMetricsWhereClause(options.jobId, options.stepId, filters);
-        const sortInput = options.sort ?? { field: 'timestamp', order: 'desc' };
+        // Build sort
+        const sortInput = options.sort ?? { field: 'startTimeUnixNano', order: 'asc' };
         const sortFieldMap = {
-            name: metricsTable.name,
-            value: metricsTable.value,
-            timestamp: metricsTable.timestamp,
-            createdAt: metricsTable.created_at,
+            name: 'name',
+            startTimeUnixNano: 'start_time_unix_nano',
+            endTimeUnixNano: 'end_time_unix_nano',
         };
-        const total = await this.db.$count(metricsTable, where);
+        const sortField = sortFieldMap[sortInput.field];
+        const sortOrder = sortInput.order === 'asc' ? 'ASC' : 'DESC';
+        // For step queries, use a recursive CTE to get descendant spans
+        if (options.stepId) {
+            return this._getStepSpansRecursive(options.stepId, sortField, sortOrder, filters);
+        }
+        // Build WHERE clause for job queries
+        const where = this._buildSpansWhereClause(options.jobId, undefined, filters);
+        // Get total count
+        const total = await this.db.$count(spansTable, where);
         if (!total) {
             return {
-                metrics: [],
+                spans: [],
                 total: 0,
             };
         }
-        const sortField = sortFieldMap[sortInput.field];
-        const orderByClause = sortInput.order === 'asc' ? asc(sortField) : desc(sortField);
-        const metrics = await this.db
+        const sortFieldColumn = sortFieldMap[sortInput.field];
+        const orderByClause = sortInput.order === 'asc'
+            ? asc(spansTable[sortFieldColumn])
+            : desc(spansTable[sortFieldColumn]);
+        const rows = await this.db
             .select({
-            id: metricsTable.id,
-            jobId: metricsTable.job_id,
-            stepId: metricsTable.step_id,
-            name: metricsTable.name,
-            value: metricsTable.value,
-            attributes: metricsTable.attributes,
-            type: metricsTable.type,
-            timestamp: metricsTable.timestamp,
-            createdAt: metricsTable.created_at,
+            id: spansTable.id,
+            traceId: spansTable.trace_id,
+            spanId: spansTable.span_id,
+            parentSpanId: spansTable.parent_span_id,
+            jobId: spansTable.job_id,
+            stepId: spansTable.step_id,
+            name: spansTable.name,
+            kind: spansTable.kind,
+            startTimeUnixNano: spansTable.start_time_unix_nano,
+            endTimeUnixNano: spansTable.end_time_unix_nano,
+            statusCode: spansTable.status_code,
+            statusMessage: spansTable.status_message,
+            attributes: spansTable.attributes,
+            events: spansTable.events,
         })
-            .from(metricsTable)
+            .from(spansTable)
             .where(where)
             .orderBy(orderByClause);
+        // Cast kind and statusCode to proper types, convert BigInt to string for JSON serialization
+        const spans = rows.map((row) => ({
+            ...row,
+            kind: row.kind,
+            statusCode: row.statusCode,
+            // Convert BigInt to string for JSON serialization
+            startTimeUnixNano: row.startTimeUnixNano?.toString() ?? null,
+            endTimeUnixNano: row.endTimeUnixNano?.toString() ?? null,
+        }));
         return {
-            metrics,
+            spans,
             total,
         };
     }
-    async _deleteMetrics(options) {
+    /**
+     * Get spans for a step using a recursive CTE to traverse the span hierarchy.
+     * This returns the step's span and all its descendant spans (children, grandchildren, etc.)
+     */
+    async _getStepSpansRecursive(stepId, sortField, sortOrder, _filters) {
+        const schemaName = this.schema;
+        // Use a recursive CTE to find all descendant spans
+        // 1. Base case: find the span with step_id = stepId
+        // 2. Recursive case: find all spans where parent_span_id = span_id of a span we've already found
+        const query = sql `
+      WITH RECURSIVE span_tree AS (
+        -- Base case: the span(s) for the step
+        SELECT * FROM ${sql.identifier(schemaName)}.spans WHERE step_id = ${stepId}::uuid
+        UNION ALL
+        -- Recursive case: children of spans we've found
+        SELECT s.* FROM ${sql.identifier(schemaName)}.spans s
+        INNER JOIN span_tree st ON s.parent_span_id = st.span_id
+      )
+      SELECT
+        id,
+        trace_id as "traceId",
+        span_id as "spanId",
+        parent_span_id as "parentSpanId",
+        job_id as "jobId",
+        step_id as "stepId",
+        name,
+        kind,
+        start_time_unix_nano as "startTimeUnixNano",
+        end_time_unix_nano as "endTimeUnixNano",
+        status_code as "statusCode",
+        status_message as "statusMessage",
+        attributes,
+        events
+      FROM span_tree
+      ORDER BY ${sql.identifier(sortField)} ${sql.raw(sortOrder)}
+    `;
+        // Raw SQL returns numeric types as strings, so we type them as such
+        const rows = (await this.db.execute(query));
+        // Convert types: raw SQL returns numeric types as strings
+        const spans = rows.map((row) => ({
+            ...row,
+            // Convert id to number (bigserial comes as string from raw SQL)
+            id: typeof row.id === 'string' ? Number.parseInt(row.id, 10) : row.id,
+            // Convert kind and statusCode to proper types
+            kind: (typeof row.kind === 'string' ? Number.parseInt(row.kind, 10) : row.kind),
+            statusCode: (typeof row.statusCode === 'string' ? Number.parseInt(row.statusCode, 10) : row.statusCode),
+            // Convert BigInt to string for JSON serialization
+            startTimeUnixNano: row.startTimeUnixNano?.toString() ?? null,
+            endTimeUnixNano: row.endTimeUnixNano?.toString() ?? null,
+        }));
+        return {
+            spans,
+            total: spans.length,
+        };
+    }
+    /**
+     * Internal method to delete all spans for a job.
+     */
+    async _deleteSpans(options) {
         const result = await this.db
-            .delete(this.tables.metricsTable)
-            .where(eq(this.tables.metricsTable.job_id, options.jobId))
-            .returning({ id: this.tables.metricsTable.id });
+            .delete(this.tables.spansTable)
+            .where(eq(this.tables.spansTable.job_id, options.jobId))
+            .returning({ id: this.tables.spansTable.id });
         return result.length;
     }
-    _buildMetricsWhereClause(jobId, stepId, filters) {
-        const metricsTable = this.tables.metricsTable;
-        return and(jobId ? eq(metricsTable.job_id, jobId) : undefined, stepId ? eq(metricsTable.step_id, stepId) : undefined, filters?.name
+    /**
+     * Build WHERE clause for spans queries (used for job queries only).
+     * When querying by jobId, we find all spans that share the same trace_id
+     * as spans with that job. This includes spans from external libraries that
+     * don't have the duron.job.id attribute but are part of the same trace.
+     *
+     * Note: Step queries are handled separately by _getStepSpansRecursive using
+     * a recursive CTE to traverse the span hierarchy.
+     */
+    _buildSpansWhereClause(jobId, _stepId, filters) {
+        const spansTable = this.tables.spansTable;
+        // Build condition for finding spans by trace_id (includes external spans)
+        let traceCondition;
+        if (jobId) {
+            // Find all spans that share a trace_id with any span that has this job_id
+            // This includes external spans (like from AI SDK) that don't have duron.job.id
+            traceCondition = inArray(spansTable.trace_id, this.db.select({ traceId: spansTable.trace_id }).from(spansTable).where(eq(spansTable.job_id, jobId)));
+        }
+        return and(traceCondition, filters?.name
             ? Array.isArray(filters.name)
-                ? or(...filters.name.map((n) => ilike(metricsTable.name, `%${n}%`)))
-                : ilike(metricsTable.name, `%${filters.name}%`)
-            : undefined, filters?.type
-            ? inArray(metricsTable.type, Array.isArray(filters.type) ? filters.type : [filters.type])
-            : undefined, filters?.timestampRange && filters.timestampRange.length === 2
-            ? between(metricsTable.timestamp, filters.timestampRange[0], filters.timestampRange[1])
-            : undefined, ...(filters?.attributesFilter && Object.keys(filters.attributesFilter).length > 0
-            ? this.#buildJsonbWhereConditions(filters.attributesFilter, metricsTable.attributes)
+                ? or(...filters.name.map((n) => ilike(spansTable.name, `%${n}%`)))
+                : ilike(spansTable.name, `%${filters.name}%`)
+            : undefined, filters?.kind ? inArray(spansTable.kind, Array.isArray(filters.kind) ? filters.kind : [filters.kind]) : undefined, filters?.statusCode
+            ? inArray(spansTable.status_code, Array.isArray(filters.statusCode) ? filters.statusCode : [filters.statusCode])
+            : undefined, filters?.traceId ? eq(spansTable.trace_id, filters.traceId) : undefined, ...(filters?.attributesFilter && Object.keys(filters.attributesFilter).length > 0
+            ? this.#buildJsonbWhereConditions(filters.attributesFilter, spansTable.attributes)
             : []));
     }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Build WHERE conditions for JSONB filter using individual property checks.
+     * Each property becomes a separate condition using ->> operator and ILIKE for case-insensitive matching.
+     * Supports nested properties via dot notation and arrays.
+     *
+     * Example:
+     *   { "email": "tincho@gmail", "address.name": "nicolas", "products": ["chicle"] }
+     *   Generates:
+     *     input ->> 'email' ILIKE '%tincho@gmail%'
+     *     AND input ->> 'address' ->> 'name' ILIKE '%nicolas%'
+     *     AND EXISTS (SELECT 1 FROM jsonb_array_elements_text(input -> 'products') AS elem WHERE LOWER(elem) ILIKE LOWER('%chicle%'))
+     *
+     * @param filter - Flat record with dot-notation keys (e.g., { "email": "test", "address.name": "value", "products": ["chicle"] })
+     * @param jsonbColumn - The JSONB column name
+     * @returns Array of SQL conditions
+     */
     #buildJsonbWhereConditions(filter, jsonbColumn) {
         const conditions = [];
         for (const [key, value] of Object.entries(filter)) {
@@ -1019,11 +1339,16 @@ export class PostgresBaseAdapter extends Adapter {
             if (parts.length === 0) {
                 continue;
             }
+            // Build the JSONB path expression step by step
+            // For "address.name": input -> 'address' ->> 'name'  (-> for intermediate, ->> for final)
+            // For "email": input ->> 'email'  (->> for single level)
             let jsonbPath = sql `${jsonbColumn}`;
             if (parts.length === 1) {
+                // Single level: use ->> directly
                 jsonbPath = sql `${jsonbPath} ->> ${parts[0]}`;
             }
             else {
+                // Nested: use -> for intermediate steps, ->> for final step
                 for (let i = 0; i < parts.length - 1; i++) {
                     const part = parts[i];
                     if (part) {
@@ -1035,9 +1360,12 @@ export class PostgresBaseAdapter extends Adapter {
                     jsonbPath = sql `${jsonbPath} ->> ${lastPart}`;
                 }
             }
+            // Handle array values - check if JSONB array contains at least one of the values
             if (Array.isArray(value)) {
+                // Build condition: check if any element in the JSONB array matches any value in the filter array
                 const arrayValueConditions = value.map((arrayValue) => {
                     const arrayValueStr = String(arrayValue);
+                    // Get the array from JSONB: input -> 'products'
                     let arrayPath = sql `${jsonbColumn}`;
                     for (let i = 0; i < parts.length - 1; i++) {
                         const part = parts[i];
@@ -1049,6 +1377,7 @@ export class PostgresBaseAdapter extends Adapter {
                     if (lastPart) {
                         arrayPath = sql `${arrayPath} -> ${lastPart}`;
                     }
+                    // Check if the JSONB array contains the value (case-insensitive for strings)
                     if (typeof arrayValue === 'string') {
                         return sql `EXISTS (
               SELECT 1
@@ -1057,30 +1386,62 @@ export class PostgresBaseAdapter extends Adapter {
             )`;
                     }
                     else {
+                        // For non-string values, use exact containment
                         return sql `${arrayPath} @> ${sql.raw(JSON.stringify([arrayValue]))}::jsonb`;
                     }
                 });
+                // Combine array conditions with OR (at least one must match)
                 if (arrayValueConditions.length > 0) {
                     conditions.push(arrayValueConditions.reduce((acc, condition, idx) => (idx === 0 ? condition : sql `${acc} OR ${condition}`)));
                 }
             }
             else if (typeof value === 'string') {
+                // String values: use ILIKE for case-insensitive partial matching
                 conditions.push(sql `COALESCE(${jsonbPath}, '') ILIKE ${`%${value}%`}`);
             }
             else {
+                // Non-string, non-array values: use exact match
+                // Convert JSONB value to text for comparison
                 conditions.push(sql `${jsonbPath}::text = ${String(value)}`);
             }
         }
         return conditions;
     }
+    // ============================================================================
+    // Protected Methods
+    // ============================================================================
+    /**
+     * Send a PostgreSQL notification.
+     *
+     * @param event - The event name
+     * @param data - The data to send
+     * @returns Promise resolving to `void`
+     */
     async _notify(_event, _data) {
+        // do nothing
     }
+    /**
+     * Listen for PostgreSQL notifications.
+     *
+     * @param event - The event name to listen for
+     * @param callback - Callback function to handle notifications
+     * @returns Promise resolving to an object with an `unlisten` function
+     */
     async _listen(_event, _callback) {
+        // do nothing
         return {
             unlisten: () => {
+                // do nothing
             },
         };
     }
+    /**
+     * Map database query results to the expected format.
+     * Can be overridden by subclasses to handle different result formats.
+     *
+     * @param result - The raw database query result
+     * @returns The mapped result
+     */
     _map(result) {
         return result;
     }