@mastra/duckdb 1.3.2 → 1.4.0-alpha.1

package/dist/{observability-TS5QIHIC.js → observability-M35AJUGT.js}

@@ -1,15 +1,32 @@
 import { DuckDBConnection } from './chunk-4LIZE4MC.js';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { BRANCH_SPAN_TYPES, ObservabilityStorage, createStorageErrorId, toTraceSpans, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
+import { BRANCH_SPAN_TYPES, ObservabilityStorage, createStorageErrorId, listTracesArgsSchema, toTraceSpans, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
 import { EntityType } from '@mastra/core/observability';
 import { parseFieldKey } from '@mastra/core/utils';
+import { coreFeatures } from '@mastra/core/features';
 
 // src/storage/domains/observability/ddl.ts
+var SPAN_EVENTS_CURSOR_SEQUENCE_DDL = `
+CREATE SEQUENCE IF NOT EXISTS span_events_cursor_id_seq START 1
+`;
+var METRIC_EVENTS_CURSOR_SEQUENCE_DDL = `
+CREATE SEQUENCE IF NOT EXISTS metric_events_cursor_id_seq START 1
+`;
+var LOG_EVENTS_CURSOR_SEQUENCE_DDL = `
+CREATE SEQUENCE IF NOT EXISTS log_events_cursor_id_seq START 1
+`;
+var SCORE_EVENTS_CURSOR_SEQUENCE_DDL = `
+CREATE SEQUENCE IF NOT EXISTS score_events_cursor_id_seq START 1
+`;
+var FEEDBACK_EVENTS_CURSOR_SEQUENCE_DDL = `
+CREATE SEQUENCE IF NOT EXISTS feedback_events_cursor_id_seq START 1
+`;
 var SPAN_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS span_events (
   -- Event metadata
   eventType VARCHAR NOT NULL,
   timestamp TIMESTAMP NOT NULL,
+  cursorId BIGINT,
 
   -- IDs
   traceId VARCHAR NOT NULL,
@@ -56,6 +73,7 @@ var METRIC_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS metric_events (
   -- Event metadata
   timestamp TIMESTAMP NOT NULL,
+  cursorId BIGINT,
 
   -- IDs
   metricId VARCHAR NOT NULL PRIMARY KEY,
@@ -108,6 +126,7 @@ var LOG_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS log_events (
   -- Event metadata
   timestamp TIMESTAMP NOT NULL,
+  cursorId BIGINT,
 
   -- IDs
   logId VARCHAR NOT NULL PRIMARY KEY,
@@ -155,6 +174,7 @@ var SCORE_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS score_events (
   -- Event metadata
   timestamp TIMESTAMP NOT NULL,
+  cursorId BIGINT,
 
   -- IDs
   scoreId VARCHAR NOT NULL PRIMARY KEY,
@@ -206,6 +226,7 @@ var FEEDBACK_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS feedback_events (
   -- Event metadata
   timestamp TIMESTAMP NOT NULL,
+  cursorId BIGINT,
 
   -- IDs
   feedbackId VARCHAR NOT NULL PRIMARY KEY,
@@ -254,11 +275,34 @@ CREATE TABLE IF NOT EXISTS feedback_events (
   metadata JSON,
   scope JSON
 )`;
-var ALL_DDL = [SPAN_EVENTS_DDL, METRIC_EVENTS_DDL, LOG_EVENTS_DDL, SCORE_EVENTS_DDL, FEEDBACK_EVENTS_DDL];
+var ALL_DDL = [
+  SPAN_EVENTS_CURSOR_SEQUENCE_DDL,
+  METRIC_EVENTS_CURSOR_SEQUENCE_DDL,
+  LOG_EVENTS_CURSOR_SEQUENCE_DDL,
+  SCORE_EVENTS_CURSOR_SEQUENCE_DDL,
+  FEEDBACK_EVENTS_CURSOR_SEQUENCE_DDL,
+  SPAN_EVENTS_DDL,
+  METRIC_EVENTS_DDL,
+  LOG_EVENTS_DDL,
+  SCORE_EVENTS_DDL,
+  FEEDBACK_EVENTS_DDL
+];
 var ALL_MIGRATIONS = [
-  // Span events
+  `CREATE SEQUENCE IF NOT EXISTS span_events_cursor_id_seq START 1`,
+  `CREATE SEQUENCE IF NOT EXISTS metric_events_cursor_id_seq START 1`,
+  `CREATE SEQUENCE IF NOT EXISTS log_events_cursor_id_seq START 1`,
+  `CREATE SEQUENCE IF NOT EXISTS score_events_cursor_id_seq START 1`,
+  `CREATE SEQUENCE IF NOT EXISTS feedback_events_cursor_id_seq START 1`,
+  // Existing rows intentionally keep NULL cursorId values; delta polling only
+  // applies to rows written by insert paths that explicitly call nextval().
+  // Databases upgraded from a prior version may still carry a
+  // `DEFAULT nextval(...)` on cursorId, which breaks DuckDB WAL replay; that
+  // remediation lives in `dropLegacyCursorIdDefaults` and only runs when the
+  // bad default is detected in information_schema.
+  `ALTER TABLE span_events ADD COLUMN IF NOT EXISTS cursorId BIGINT`,
   `ALTER TABLE span_events ADD COLUMN IF NOT EXISTS entityVersionId VARCHAR`,
-  // Metrics
+  // Metrics. Legacy rows remain page-visible but are not part of delta polling.
+  `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS cursorId BIGINT`,
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS entityVersionId VARCHAR`,
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS parentEntityVersionId VARCHAR`,
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS rootEntityVersionId VARCHAR`,
@@ -282,7 +326,8 @@ var ALL_MIGRATIONS = [
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS costMetadata JSON`,
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS metadata JSON`,
   `ALTER TABLE metric_events ADD COLUMN IF NOT EXISTS scope JSON`,
-  // Logs
+  // Logs. Legacy rows remain page-visible but are not part of delta polling.
+  `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS cursorId BIGINT`,
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS entityVersionId VARCHAR`,
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS parentEntityVersionId VARCHAR`,
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS rootEntityVersionId VARCHAR`,
@@ -306,7 +351,8 @@ var ALL_MIGRATIONS = [
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS tags JSON`,
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS metadata JSON`,
   `ALTER TABLE log_events ADD COLUMN IF NOT EXISTS scope JSON`,
-  // Scores
+  // Scores. Legacy rows remain page-visible but are not part of delta polling.
+  `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS cursorId BIGINT`,
   `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS entityVersionId VARCHAR`,
   `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS parentEntityVersionId VARCHAR`,
   `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS rootEntityVersionId VARCHAR`,
@@ -334,7 +380,8 @@ var ALL_MIGRATIONS = [
   `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS source VARCHAR`,
   `ALTER TABLE score_events ADD COLUMN IF NOT EXISTS scoreSource VARCHAR`,
   `ALTER TABLE score_events ALTER COLUMN traceId DROP NOT NULL`,
-  // Feedback
+  // Feedback. Legacy rows remain page-visible but are not part of delta polling.
+  `ALTER TABLE feedback_events ADD COLUMN IF NOT EXISTS cursorId BIGINT`,
   `ALTER TABLE feedback_events ADD COLUMN IF NOT EXISTS entityVersionId VARCHAR`,
   `ALTER TABLE feedback_events ADD COLUMN IF NOT EXISTS parentEntityVersionId VARCHAR`,
   `ALTER TABLE feedback_events ADD COLUMN IF NOT EXISTS rootEntityVersionId VARCHAR`,
@@ -598,6 +645,45 @@ function parseJsonArray(value) {
   const parsed = parseJson(value);
   return Array.isArray(parsed) ? parsed : null;
 }
+var OBSERVABILITY_DELTA_POLLING_FEATURE = "observability-delta-polling";
+function deltaPollingFeatureEnabled() {
+  return coreFeatures.has(OBSERVABILITY_DELTA_POLLING_FEATURE);
+}
+function assertDeltaPollingEnabled() {
+  if (deltaPollingFeatureEnabled()) {
+    return;
+  }
+  throw new MastraError({
+    id: "OBSERVABILITY_DELTA_POLLING_NOT_SUPPORTED",
+    domain: ErrorDomain.MASTRA_OBSERVABILITY,
+    category: ErrorCategory.SYSTEM,
+    text: "This storage provider does not support observability delta polling"
+  });
+}
+function encodeDeltaCursor(value) {
+  return String(value ?? 0);
+}
+function validateCursorId(cursor) {
+  if (!/^\d+$/.test(cursor)) {
+    throw new MastraError({
+      id: "OBSERVABILITY_INVALID_DELTA_CURSOR",
+      domain: ErrorDomain.MASTRA_OBSERVABILITY,
+      category: ErrorCategory.USER,
+      text: "Invalid observability delta cursor"
+    });
+  }
+  return cursor;
+}
+function extendWhereClause(baseClause, extraConditions) {
+  const conditions = extraConditions.filter(Boolean);
+  if (conditions.length === 0) {
+    return baseClause;
+  }
+  if (!baseClause) {
+    return `WHERE ${conditions.join(" AND ")}`;
+  }
+  return `${baseClause} AND ${conditions.join(" AND ")}`;
+}
 
 // src/storage/domains/observability/feedback.ts
 var FEEDBACK_GROUP_BY_COLUMNS = /* @__PURE__ */ new Set([
@@ -794,7 +880,7 @@ async function createFeedback(db, args) {
   const feedbackUserId = f.feedbackUserId ?? f.userId ?? null;
   await db.execute(
     `INSERT INTO feedback_events (
-      feedbackId, timestamp, traceId, spanId, experimentId,
+      feedbackId, timestamp, cursorId, traceId, spanId, experimentId,
       entityType, entityId, entityName, entityVersionId, parentEntityVersionId, parentEntityType, parentEntityId, parentEntityName, rootEntityVersionId, rootEntityType, rootEntityId, rootEntityName,
       userId, organizationId, resourceId, runId, sessionId, threadId, requestId, environment, executionSource, serviceName,
       feedbackUserId, sourceId, feedbackSource, feedbackType, value, comment, tags, metadata, scope
@@ -802,6 +888,7 @@ async function createFeedback(db, args) {
      VALUES (${[
       v(f.feedbackId),
       v(f.timestamp),
+      "nextval('feedback_events_cursor_id_seq')",
       v(f.traceId),
       v(f.spanId ?? null),
       v(f.experimentId ?? null),
@@ -849,6 +936,7 @@ async function batchCreateFeedback(db, args) {
     return `(${[
       v(legacyFeedback.feedbackId),
       v(legacyFeedback.timestamp),
+      "nextval('feedback_events_cursor_id_seq')",
       v(legacyFeedback.traceId),
       v(legacyFeedback.spanId ?? null),
       v(legacyFeedback.experimentId ?? null),
@@ -887,7 +975,7 @@ async function batchCreateFeedback(db, args) {
   });
   await db.execute(
     `INSERT INTO feedback_events (
-      feedbackId, timestamp, traceId, spanId, experimentId,
+      feedbackId, timestamp, cursorId, traceId, spanId, experimentId,
       entityType, entityId, entityName, entityVersionId, parentEntityVersionId, parentEntityType, parentEntityId, parentEntityName, rootEntityVersionId, rootEntityType, rootEntityId, rootEntityName,
       userId, organizationId, resourceId, runId, sessionId, threadId, requestId, environment, executionSource, serviceName,
       feedbackUserId, sourceId, feedbackSource, feedbackType, value, comment, tags, metadata, scope
@@ -897,15 +985,41 @@ async function batchCreateFeedback(db, args) {
   );
 }
 async function listFeedback(db, args) {
-  const filters = args.filters ?? {};
-  const page = Number(args.pagination?.page ?? 0);
-  const perPage = Number(args.pagination?.perPage ?? 10);
-  const orderBy = { field: args.orderBy?.field ?? "timestamp", direction: args.orderBy?.direction ?? "DESC" };
+  const { mode, filters, pagination, orderBy, after, limit } = listFeedbackArgsSchema.parse(args);
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
   const { clause: filterClause, params: filterParams } = buildWhereClause(filters, {
     source: "feedbackSource"
   });
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getStreamHeadCursor(db);
+    if (after === void 0) {
+      return {
+        feedback: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const deltaWhereClause = extendWhereClause(filterClause, ["cursorId IS NOT NULL", `cursorId > CAST(? AS BIGINT)`]);
+    const rows2 = await db.query(
+      `SELECT * FROM feedback_events ${deltaWhereClause} ORDER BY cursorId ASC LIMIT ?`,
+      [...filterParams, afterCursorId, limit + 1]
+    );
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.cursorId,
+      feedback: rowToFeedbackRecord(row)
+    }));
+    return {
+      feedback: visibleRows.map((row) => row.feedback),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
+    };
+  }
   const orderByClause = buildOrderByClause(orderBy);
   const { clause: paginationClause, params: paginationParams } = buildPaginationClause({ page, perPage });
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getDeltaCursor(db, filterClause, filterParams) : void 0;
   const countResult = await db.query(
     `SELECT COUNT(*) as total FROM feedback_events ${filterClause}`,
     filterParams
@@ -917,9 +1031,26 @@ async function listFeedback(db, args) {
   );
   return {
     pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
-    feedback: rows.map((row) => rowToFeedbackRecord(row))
+    feedback: rows.map((row) => rowToFeedbackRecord(row)),
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
   };
 }
+async function getDeltaCursor(db, filterClause, filterParams) {
+  const rows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM feedback_events ${filterClause}`,
+    filterParams
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM feedback_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getStreamHeadCursor(db) {
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM feedback_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
 async function getFeedbackAggregate(db, args) {
   const aggSql = getAggregationSql(args.aggregation);
   const { clause, params } = buildFeedbackWhereClause(args, true);
@@ -1047,11 +1178,10 @@ async function getFeedbackPercentiles(db, args) {
   }
   return { series };
 }
-
-// src/storage/domains/observability/logs.ts
 var COLUMNS = [
   "logId",
   "timestamp",
+  "cursorId",
   "level",
   "message",
   "data",
@@ -1128,6 +1258,7 @@ async function batchCreateLogs(db, args) {
     return `(${[
       v(log.logId),
       v(log.timestamp),
+      "nextval('log_events_cursor_id_seq')",
       v(log.level),
       v(log.message),
       jsonV(log.data),
@@ -1164,13 +1295,40 @@ async function batchCreateLogs(db, args) {
   await db.execute(`INSERT INTO log_events (${COLUMNS_SQL}) VALUES ${tuples.join(",\n")} ON CONFLICT DO NOTHING`);
 }
 async function listLogs(db, args) {
-  const filters = args.filters ?? {};
-  const page = Number(args.pagination?.page ?? 0);
-  const perPage = Number(args.pagination?.perPage ?? 10);
-  const orderBy = { field: args.orderBy?.field ?? "timestamp", direction: args.orderBy?.direction ?? "DESC" };
-  const { clause: filterClause, params: filterParams } = buildWhereClause(filters);
+  const { mode, filters, pagination, orderBy, after, limit } = listLogsArgsSchema.parse(args);
+  const filterRecord = filters;
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
+  const { clause: filterClause, params: filterParams } = buildWhereClause(filterRecord);
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getStreamHeadCursor2(db);
+    if (after === void 0) {
+      return {
+        logs: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const deltaWhereClause = extendWhereClause(filterClause, ["cursorId IS NOT NULL", `cursorId > CAST(? AS BIGINT)`]);
+    const rows2 = await db.query(
+      `SELECT * FROM log_events ${deltaWhereClause} ORDER BY cursorId ASC LIMIT ?`,
+      [...filterParams, afterCursorId, limit + 1]
+    );
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.cursorId,
+      log: rowToLogRecord(row)
+    }));
+    return {
+      logs: visibleRows.map((row) => row.log),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
+    };
+  }
   const orderByClause = buildOrderByClause(orderBy);
   const { clause: paginationClause, params: paginationParams } = buildPaginationClause({ page, perPage });
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getDeltaCursor2(db, filterClause, filterParams) : void 0;
   const countResult = await db.query(
     `SELECT COUNT(*) as total FROM log_events ${filterClause}`,
     filterParams
@@ -1183,9 +1341,26 @@ async function listLogs(db, args) {
   const logs = rows.map((row) => rowToLogRecord(row));
   return {
     pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
-    logs
+    logs,
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
   };
 }
+async function getDeltaCursor2(db, filterClause, filterParams) {
+  const rows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM log_events ${filterClause}`,
+    filterParams
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM log_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getStreamHeadCursor2(db) {
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM log_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
 function resolveDistinctColumnSql(distinctColumn) {
   if (!distinctColumn) {
     throw new Error(`count_distinct aggregation requires a 'distinctColumn' argument`);
@@ -1242,6 +1417,7 @@ function buildMetricNameFilter(name) {
 var METRIC_COLUMNS = [
   "metricId",
   "timestamp",
+  "cursorId",
   "name",
   "value",
   "traceId",
@@ -1390,6 +1566,7 @@ async function batchCreateMetrics(db, args) {
     return `(${[
       v(m.metricId),
       v(m.timestamp),
+      "nextval('metric_events_cursor_id_seq')",
       v(m.name),
       v(m.value),
       v(m.traceId ?? null),
@@ -1433,13 +1610,40 @@ async function batchCreateMetrics(db, args) {
   );
 }
 async function listMetrics(db, args) {
-  const filters = args.filters ?? {};
-  const page = Number(args.pagination?.page ?? 0);
-  const perPage = Number(args.pagination?.perPage ?? 10);
-  const orderBy = { field: args.orderBy?.field ?? "timestamp", direction: args.orderBy?.direction ?? "DESC" };
-  const { clause: filterClause, params: filterParams } = buildWhereClause(filters);
+  const { mode, filters, pagination, orderBy, after, limit } = listMetricsArgsSchema.parse(args);
+  const filterRecord = filters;
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
+  const { clause: filterClause, params: filterParams } = buildWhereClause(filterRecord);
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getStreamHeadCursor3(db);
+    if (after === void 0) {
+      return {
+        metrics: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const deltaWhereClause = extendWhereClause(filterClause, ["cursorId IS NOT NULL", `cursorId > CAST(? AS BIGINT)`]);
+    const rows2 = await db.query(
+      `SELECT * FROM metric_events ${deltaWhereClause} ORDER BY cursorId ASC LIMIT ?`,
+      [...filterParams, afterCursorId, limit + 1]
+    );
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.cursorId,
+      metric: rowToMetricRecord(row)
+    }));
+    return {
+      metrics: visibleRows.map((row) => row.metric),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
+    };
+  }
   const orderByClause = buildOrderByClause(orderBy);
   const { clause: paginationClause, params: paginationParams } = buildPaginationClause({ page, perPage });
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getDeltaCursor3(db, filterClause, filterParams) : void 0;
   const countResult = await db.query(
     `SELECT COUNT(*) AS total FROM metric_events ${filterClause}`,
     filterParams
@@ -1451,9 +1655,26 @@ async function listMetrics(db, args) {
   );
   return {
     pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
-    metrics: rows.map((row) => rowToMetricRecord(row))
+    metrics: rows.map((row) => rowToMetricRecord(row)),
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
   };
 }
+async function getDeltaCursor3(db, filterClause, filterParams) {
+  const rows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM metric_events ${filterClause}`,
+    filterParams
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM metric_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getStreamHeadCursor3(db) {
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM metric_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
 async function getMetricAggregate(db, args) {
   const aggSql = getAggregationSql2(args.aggregation, "value", args.distinctColumn);
   const { clause: nameClause, params: nameParams } = buildMetricNameFilter(args.name);
@@ -1732,11 +1953,42 @@ async function getMetricLabelValues(db, args) {
   );
   return { values: rows.map((r) => r.val) };
 }
+var CURSOR_ID_TABLES = ["span_events", "metric_events", "log_events", "score_events", "feedback_events"];
+async function dropLegacyCursorIdDefaults(db) {
+  const rows = await db.query(
+    `SELECT table_name FROM information_schema.columns
+     WHERE column_name = 'cursorId'
+       AND column_default IS NOT NULL
+       AND table_name IN (${CURSOR_ID_TABLES.map((t) => `'${t}'`).join(", ")})`
+  );
+  if (rows.length === 0) return;
+  await db.executeBatch(rows.map((row) => `ALTER TABLE ${row.table_name} ALTER COLUMN cursorId DROP DEFAULT`));
+}
 var SIGNAL_MIGRATIONS = [
-  { table: "metric_events", createDDL: METRIC_EVENTS_DDL, idColumn: "metricId" },
-  { table: "log_events", createDDL: LOG_EVENTS_DDL, idColumn: "logId" },
-  { table: "score_events", createDDL: SCORE_EVENTS_DDL, idColumn: "scoreId" },
-  { table: "feedback_events", createDDL: FEEDBACK_EVENTS_DDL, idColumn: "feedbackId" }
+  {
+    table: "metric_events",
+    createDDL: METRIC_EVENTS_DDL,
+    idColumn: "metricId",
+    cursorSequenceDDL: METRIC_EVENTS_CURSOR_SEQUENCE_DDL
+  },
+  {
+    table: "log_events",
+    createDDL: LOG_EVENTS_DDL,
+    idColumn: "logId",
+    cursorSequenceDDL: LOG_EVENTS_CURSOR_SEQUENCE_DDL
+  },
+  {
+    table: "score_events",
+    createDDL: SCORE_EVENTS_DDL,
+    idColumn: "scoreId",
+    cursorSequenceDDL: SCORE_EVENTS_CURSOR_SEQUENCE_DDL
+  },
+  {
+    table: "feedback_events",
+    createDDL: FEEDBACK_EVENTS_DDL,
+    idColumn: "feedbackId",
+    cursorSequenceDDL: FEEDBACK_EVENTS_CURSOR_SEQUENCE_DDL
+  }
 ];
 async function tableExists(db, table) {
   const rows = await db.query(
@@ -1796,7 +2048,7 @@ async function checkSignalTablesMigrationStatus(db) {
   };
 }
 async function migrateSignalTables(db, logger) {
-  for (const { table, createDDL, idColumn } of SIGNAL_MIGRATIONS) {
+  for (const { table, createDDL, idColumn, cursorSequenceDDL } of SIGNAL_MIGRATIONS) {
     if (!await tableExists(db, table)) continue;
     if (await hasPrimaryKey(db, table)) continue;
     logger?.info?.(`Migrating ${table} to schema with ${idColumn} PRIMARY KEY`);
@@ -1805,6 +2057,7 @@ async function migrateSignalTables(db, logger) {
     let originalRenamed = false;
     let swapCompleted = false;
     try {
+      await db.execute(cursorSequenceDDL);
       await db.execute(buildTemporaryTableDDL(createDDL, table, temp));
       const newColumns = await getColumns(db, temp);
       const currentColumns = new Set(await getColumns(db, table));
@@ -2034,7 +2287,7 @@ async function createScore(db, args) {
   const scoreSource = s.scoreSource ?? s.source ?? null;
   await db.execute(
     `INSERT INTO score_events (
-      scoreId, timestamp, traceId, spanId, experimentId, scoreTraceId,
+      scoreId, timestamp, cursorId, traceId, spanId, experimentId, scoreTraceId,
       entityType, entityId, entityName, entityVersionId, parentEntityVersionId, parentEntityType, parentEntityId, parentEntityName, rootEntityVersionId, rootEntityType, rootEntityId, rootEntityName,
       userId, organizationId, resourceId, runId, sessionId, threadId, requestId, environment, executionSource, serviceName,
       scorerId, scorerVersion, scoreSource, score, reason, tags, metadata, scope
@@ -2042,6 +2295,7 @@ async function createScore(db, args) {
      VALUES (${[
       v(s.scoreId),
       v(s.timestamp),
+      "nextval('score_events_cursor_id_seq')",
       v(s.traceId),
       v(s.spanId ?? null),
       v(s.experimentId ?? null),
@@ -2088,6 +2342,7 @@ async function batchCreateScores(db, args) {
     return `(${[
       v(legacyScore.scoreId),
       v(legacyScore.timestamp),
+      "nextval('score_events_cursor_id_seq')",
       v(legacyScore.traceId),
       v(legacyScore.spanId ?? null),
       v(legacyScore.experimentId ?? null),
@@ -2126,7 +2381,7 @@ async function batchCreateScores(db, args) {
   });
   await db.execute(
     `INSERT INTO score_events (
-      scoreId, timestamp, traceId, spanId, experimentId, scoreTraceId,
+      scoreId, timestamp, cursorId, traceId, spanId, experimentId, scoreTraceId,
       entityType, entityId, entityName, entityVersionId, parentEntityVersionId, parentEntityType, parentEntityId, parentEntityName, rootEntityVersionId, rootEntityType, rootEntityId, rootEntityName,
       userId, organizationId, resourceId, runId, sessionId, threadId, requestId, environment, executionSource, serviceName,
       scorerId, scorerVersion, scoreSource, score, reason, tags, metadata, scope
@@ -2136,15 +2391,41 @@ async function batchCreateScores(db, args) {
   );
 }
 async function listScores(db, args) {
-  const filters = args.filters ?? {};
-  const page = Number(args.pagination?.page ?? 0);
-  const perPage = Number(args.pagination?.perPage ?? 10);
-  const orderBy = { field: args.orderBy?.field ?? "timestamp", direction: args.orderBy?.direction ?? "DESC" };
+  const { mode, filters, pagination, orderBy, after, limit } = listScoresArgsSchema.parse(args);
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
   const { clause: filterClause, params: filterParams } = buildWhereClause(filters, {
     source: "scoreSource"
   });
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getStreamHeadCursor4(db);
+    if (after === void 0) {
+      return {
+        scores: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const deltaWhereClause = extendWhereClause(filterClause, ["cursorId IS NOT NULL", `cursorId > CAST(? AS BIGINT)`]);
+    const rows2 = await db.query(
+      `SELECT * FROM score_events ${deltaWhereClause} ORDER BY cursorId ASC LIMIT ?`,
+      [...filterParams, afterCursorId, limit + 1]
+    );
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.cursorId,
+      score: rowToScoreRecord(row)
+    }));
+    return {
+      scores: visibleRows.map((row) => row.score),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
+    };
+  }
   const orderByClause = buildOrderByClause(orderBy);
   const { clause: paginationClause, params: paginationParams } = buildPaginationClause({ page, perPage });
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getDeltaCursor4(db, filterClause, filterParams) : void 0;
   const countResult = await db.query(
     `SELECT COUNT(*) as total FROM score_events ${filterClause}`,
     filterParams
@@ -2156,9 +2437,26 @@ async function listScores(db, args) {
   );
   return {
     pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
-    scores: rows.map((row) => rowToScoreRecord(row))
+    scores: rows.map((row) => rowToScoreRecord(row)),
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
   };
 }
+async function getDeltaCursor4(db, filterClause, filterParams) {
+  const rows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM score_events ${filterClause}`,
+    filterParams
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM score_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getStreamHeadCursor4(db) {
+  const streamRows = await db.query(`SELECT max(cursorId) AS cursorId FROM score_events`);
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
 async function getScoreById(db, scoreId) {
   const rows = await db.query(`SELECT * FROM score_events WHERE scoreId = ? LIMIT 1`, [
     scoreId
@@ -2291,6 +2589,7 @@ async function getScorePercentiles(db, args) {
 var COLUMNS2 = [
   "eventType",
   "timestamp",
+  "cursorId",
   "traceId",
   "spanId",
   "parentSpanId",
@@ -2523,6 +2822,7 @@ function toValuesTuple(row) {
   return [
     v(row.eventType),
     v(row.timestamp),
+    "nextval('span_events_cursor_id_seq')",
     v(row.traceId),
     v(row.spanId),
     v(row.parentSpanId),
@@ -2777,13 +3077,152 @@ async function listTraceRows(db, args, reconstructSelect, mapRow, toSpans) {
   };
 }
 async function listTraces(db, args) {
-  return listTraceRows(
-    db,
-    args,
-    SPAN_RECONSTRUCT_SELECT,
-    rowToSpanRecord,
-    (spans) => toTraceSpans(spans)
-  );
+  const { mode, filters, pagination, orderBy, after, limit } = listTracesArgsSchema.parse(args);
+  const filterRecord = filters ?? {};
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getTraceStreamHeadCursor(db);
+    if (after === void 0) {
+      return {
+        spans: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const { prefilter: prefilter2, postAgg: postAgg2, hasChildError: hasChildError2 } = partitionAnchorFilters(filterRecord);
+    const { clause: prefilterClause2, params: prefilterParams2 } = buildWhereClause(prefilter2);
+    const prefilterParts2 = [
+      `eventType = 'start'`,
+      `parentSpanId IS NULL`,
+      `cursorId IS NOT NULL`,
+      `cursorId > CAST(? AS BIGINT)`
+    ];
+    if (prefilterClause2) prefilterParts2.push(prefilterClause2.replace(/^WHERE\s+/i, ""));
+    const prefilterWhere2 = `WHERE ${prefilterParts2.join(" AND ")}`;
+    const { clause: postAggClause2, params: postAggParams2 } = buildWhereClause(postAgg2);
+    const postAggParts2 = [];
+    if (postAggClause2) postAggParts2.push(postAggClause2.replace(/^WHERE\s+/i, ""));
+    const childErrorClause2 = buildHasChildErrorClause(hasChildError2, "root_spans");
+    if (childErrorClause2) postAggParts2.push(childErrorClause2);
+    const postAggWhere2 = postAggParts2.length > 0 ? `WHERE ${postAggParts2.join(" AND ")}` : "";
+    const outerAlias2 = "outer_root";
+    const dataSql2 = `
+      WITH candidate_roots AS (
+        SELECT traceId, spanId, cursorId
+        FROM span_events AS ${outerAlias2}
+        ${prefilterWhere2}
+      ),
+      root_spans AS (
+        SELECT reconstructed.*, candidate_roots.cursorId AS anchorCursorId
+        FROM (
+          ${SPAN_RECONSTRUCT_SELECT}
+          WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM candidate_roots)
+          GROUP BY traceId, spanId
+        ) AS reconstructed
+        INNER JOIN candidate_roots USING (traceId, spanId)
+      )
+      SELECT * FROM root_spans ${postAggWhere2} ORDER BY anchorCursorId ASC LIMIT ?
+    `;
+    const rows2 = await db.query(dataSql2, [
+      afterCursorId,
+      ...prefilterParams2,
+      ...postAggParams2,
+      limit + 1
+    ]);
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.anchorCursorId,
+      span: rowToSpanRecord(row)
+    }));
+    return {
+      spans: toTraceSpans(visibleRows.map((row) => row.span)),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
+    };
+  }
+  const { prefilter, postAgg, hasChildError } = partitionAnchorFilters(filterRecord);
+  const { clause: prefilterClause, params: prefilterParams } = buildWhereClause(prefilter);
+  const prefilterParts = [`eventType = 'start'`, `parentSpanId IS NULL`];
+  if (prefilterClause) prefilterParts.push(prefilterClause.replace(/^WHERE\s+/i, ""));
+  const prefilterWhere = `WHERE ${prefilterParts.join(" AND ")}`;
+  const outerAlias = "outer_root";
+  const orderDir = orderBy.direction.toUpperCase();
+  if (orderDir !== "ASC" && orderDir !== "DESC") {
+    throw new Error(`Invalid sort direction: ${orderBy.direction}`);
+  }
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getTraceDeltaCursor(db, filters) : void 0;
+  const canOrderInPrefilter = SAFE_PREFILTER_ORDER_FIELDS.has(orderBy.field);
+  const hasPostAggFilters = Object.keys(postAgg).length > 0 || hasChildError !== void 0 || !canOrderInPrefilter;
+  if (!hasPostAggFilters) {
+    const prefilterOrderBy = `ORDER BY timestamp ${orderDir}`;
+    const offset = page * perPage;
+    const countSql2 = `
+      SELECT COUNT(*) as total
+      FROM span_events AS ${outerAlias}
+      ${prefilterWhere}
+    `;
+    const countResult2 = await db.query(countSql2, prefilterParams);
+    const total2 = Number(countResult2[0]?.total ?? 0);
+    const pageSql = `
+      WITH page_roots AS (
+        SELECT traceId, spanId
+        FROM span_events AS ${outerAlias}
+        ${prefilterWhere}
+        ${prefilterOrderBy}
+        LIMIT ? OFFSET ?
+      )
+      ${SPAN_RECONSTRUCT_SELECT}
+      WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM page_roots)
+      GROUP BY traceId, spanId
+      ${buildOrderByClause(orderBy)}
+    `;
+    const rows2 = await db.query(pageSql, [...prefilterParams, perPage, offset]);
+    const spans2 = rows2.map((row) => rowToSpanRecord(row));
+    return {
+      pagination: { total: total2, page, perPage, hasMore: (page + 1) * perPage < total2 },
+      spans: toTraceSpans(spans2),
+      ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
+    };
+  }
+  const { clause: postAggClause, params: postAggParams } = buildWhereClause(postAgg);
+  const postAggParts = [];
+  if (postAggClause) postAggParts.push(postAggClause.replace(/^WHERE\s+/i, ""));
+  const childErrorClause = buildHasChildErrorClause(hasChildError, "root_spans");
+  if (childErrorClause) postAggParts.push(childErrorClause);
+  const postAggWhere = postAggParts.length > 0 ? `WHERE ${postAggParts.join(" AND ")}` : "";
+  const cteSql = `
+    WITH candidate_roots AS (
+      SELECT traceId, spanId
+      FROM span_events AS ${outerAlias}
+      ${prefilterWhere}
+    ),
+    root_spans AS (
+      ${SPAN_RECONSTRUCT_SELECT}
+      WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM candidate_roots)
+      GROUP BY traceId, spanId
+    )
+  `;
+  const orderByClause = buildOrderByClause(orderBy);
+  const { clause: paginationClause, params: paginationParams } = buildPaginationClause({ page, perPage });
+  const countSql = `
+    ${cteSql}
+    SELECT COUNT(*) as total FROM root_spans ${postAggWhere}
+  `;
+  const countResult = await db.query(countSql, [...prefilterParams, ...postAggParams]);
+  const total = Number(countResult[0]?.total ?? 0);
+  const dataSql = `
+    ${cteSql}
+    SELECT * FROM root_spans ${postAggWhere} ${orderByClause} ${paginationClause}
+  `;
+  const rows = await db.query(dataSql, [...prefilterParams, ...postAggParams, ...paginationParams]);
+  const spans = rows.map((row) => rowToSpanRecord(row));
+  return {
+    pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
+    spans: toTraceSpans(spans),
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
+  };
 }
 async function listTracesLight(db, args) {
   return listTraceRows(
@@ -2812,18 +3251,88 @@ async function getSpans(db, args) {
   };
 }
 async function listBranches(db, args) {
-  const filters = args.filters ?? {};
-  const page = Number(args.pagination?.page ?? 0);
-  const perPage = Number(args.pagination?.perPage ?? 10);
-  const orderBy = { field: args.orderBy?.field ?? "startedAt", direction: args.orderBy?.direction ?? "DESC" };
-  const userSpanType = filters.spanType;
+  const { mode, filters, pagination, orderBy, after, limit } = listBranchesArgsSchema.parse(args);
+  const filterRecord = filters ?? {};
+  const page = Number(pagination.page);
+  const perPage = Number(pagination.perPage);
+  const userSpanType = filterRecord.spanType;
   if (typeof userSpanType === "string" && !BRANCH_SPAN_TYPES.includes(userSpanType)) {
+    const currentDeltaCursor2 = deltaPollingFeatureEnabled() ? await getBranchDeltaCursor(db, filters) : void 0;
+    if (mode === "delta") {
+      assertDeltaPollingEnabled();
+      return {
+        branches: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: currentDeltaCursor2
+      };
+    }
     return {
       pagination: { total: 0, page, perPage, hasMore: false },
-      branches: []
+      branches: [],
+      ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor2 } : {}
+    };
+  }
+  if (mode === "delta") {
+    assertDeltaPollingEnabled();
+    const streamHeadCursor = await getBranchStreamHeadCursor(
+      db,
+      typeof userSpanType === "string" ? userSpanType : null
+    );
+    if (after === void 0) {
+      return {
+        branches: [],
+        delta: { limit, hasMore: false },
+        deltaCursor: streamHeadCursor
+      };
+    }
+    const afterCursorId = validateCursorId(after);
+    const { spanType: _spanType2, ...rest2 } = filterRecord;
+    const { prefilter: prefilter2, postAgg: postAgg2} = partitionAnchorFilters(rest2);
+    const { clause: prefilterClause2, params: prefilterFilterParams2 } = buildWhereClause(prefilter2);
+    const prefilterParts2 = [`eventType = 'start'`, `cursorId IS NOT NULL`, `cursorId > CAST(? AS BIGINT)`];
+    let spanTypeParams2;
+    if (typeof userSpanType === "string") {
+      prefilterParts2.push(`spanType = ?`);
+      spanTypeParams2 = [userSpanType];
+    } else {
+      prefilterParts2.push(`spanType IN (${BRANCH_SPAN_TYPE_PLACEHOLDERS})`);
+      spanTypeParams2 = [...BRANCH_SPAN_TYPES];
+    }
+    if (prefilterClause2) prefilterParts2.push(prefilterClause2.replace(/^WHERE\s+/i, ""));
+    const prefilterWhere2 = `WHERE ${prefilterParts2.join(" AND ")}`;
+    const prefilterParams2 = [afterCursorId, ...spanTypeParams2, ...prefilterFilterParams2];
+    const { clause: postAggClause2, params: postAggParams2 } = buildWhereClause(postAgg2);
+    const postAggWhere2 = postAggClause2 ? postAggClause2 : "";
+    const outerAlias2 = "outer_anchor";
+    const dataSql2 = `
+      WITH candidate_anchors AS (
+        SELECT traceId, spanId, cursorId
+        FROM span_events AS ${outerAlias2}
+        ${prefilterWhere2}
+      ),
+      branch_anchors AS (
+        SELECT reconstructed.*, candidate_anchors.cursorId AS anchorCursorId
+        FROM (
+          ${SPAN_RECONSTRUCT_SELECT}
+          WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM candidate_anchors)
+          GROUP BY traceId, spanId
+        ) AS reconstructed
+        INNER JOIN candidate_anchors USING (traceId, spanId)
+      )
+      SELECT * FROM branch_anchors ${postAggWhere2} ORDER BY anchorCursorId ASC LIMIT ?
+    `;
+    const rows2 = await db.query(dataSql2, [...prefilterParams2, ...postAggParams2, limit + 1]);
+    const visibleRows = rows2.slice(0, limit).map((row) => ({
+      cursorId: row.anchorCursorId,
+      branch: rowToSpanRecord(row)
+    }));
+    return {
+      branches: toTraceSpans(visibleRows.map((row) => row.branch)),
+      delta: { limit, hasMore: rows2.length > limit },
+      deltaCursor: visibleRows.length > 0 ? encodeDeltaCursor(visibleRows[visibleRows.length - 1]?.cursorId) : streamHeadCursor
     };
   }
-  const { spanType: _spanType, ...rest } = filters;
+  const { spanType: _spanType, ...rest } = filterRecord;
   const { prefilter, postAgg} = partitionAnchorFilters(rest);
   const { clause: prefilterClause, params: prefilterFilterParams } = buildWhereClause(prefilter);
   const prefilterParts = [`eventType = 'start'`];
@@ -2843,6 +3352,7 @@ async function listBranches(db, args) {
   if (orderDir !== "ASC" && orderDir !== "DESC") {
     throw new Error(`Invalid sort direction: ${orderBy.direction}`);
   }
+  const currentDeltaCursor = deltaPollingFeatureEnabled() ? await getBranchDeltaCursor(db, filters) : void 0;
   const canOrderInPrefilter = SAFE_PREFILTER_ORDER_FIELDS.has(orderBy.field);
   const hasPostAggFilters = Object.keys(postAgg).length > 0 || !canOrderInPrefilter;
   if (!hasPostAggFilters) {
@@ -2858,7 +3368,8 @@ async function listBranches(db, args) {
     if (total2 === 0) {
       return {
         pagination: { total: 0, page, perPage, hasMore: false },
-        branches: []
+        branches: [],
+        ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
       };
     }
     const pageSql = `
@@ -2878,7 +3389,8 @@ async function listBranches(db, args) {
     const spans2 = rows2.map((row) => rowToSpanRecord(row));
     return {
       pagination: { total: total2, page, perPage, hasMore: (page + 1) * perPage < total2 },
-      branches: toTraceSpans(spans2)
+      branches: toTraceSpans(spans2),
+      ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
     };
   }
   const { clause: postAggClause, params: postAggParams } = buildWhereClause(postAgg);
@@ -2906,7 +3418,8 @@ async function listBranches(db, args) {
   if (total === 0) {
     return {
       pagination: { total: 0, page, perPage, hasMore: false },
-      branches: []
+      branches: [],
+      ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
     };
   }
   const dataSql = `
@@ -2917,9 +3430,151 @@ async function listBranches(db, args) {
   const spans = rows.map((row) => rowToSpanRecord(row));
   return {
     pagination: { total, page, perPage, hasMore: (page + 1) * perPage < total },
-    branches: toTraceSpans(spans)
+    branches: toTraceSpans(spans),
+    ...deltaPollingFeatureEnabled() ? { deltaCursor: currentDeltaCursor } : {}
   };
 }
+async function getTraceDeltaCursor(db, filters) {
+  const { prefilter, postAgg, hasChildError } = partitionAnchorFilters(filters ?? {});
+  const { clause: prefilterClause, params: prefilterParams } = buildWhereClause(prefilter);
+  const prefilterParts = [`eventType = 'start'`, `parentSpanId IS NULL`, `cursorId IS NOT NULL`];
+  if (prefilterClause) prefilterParts.push(prefilterClause.replace(/^WHERE\s+/i, ""));
+  const prefilterWhere = `WHERE ${prefilterParts.join(" AND ")}`;
+  const outerAlias = "outer_root";
+  const { clause: postAggClause, params: postAggParams } = buildWhereClause(postAgg);
+  const postAggParts = [];
+  if (postAggClause) postAggParts.push(postAggClause.replace(/^WHERE\s+/i, ""));
+  const childErrorClause = buildHasChildErrorClause(hasChildError, "root_spans");
+  if (childErrorClause) postAggParts.push(childErrorClause);
+  const postAggWhere = postAggParts.length > 0 ? `WHERE ${postAggParts.join(" AND ")}` : "";
+  if (postAggWhere === "") {
+    const rows2 = await db.query(
+      `SELECT max(cursorId) AS cursorId FROM span_events AS ${outerAlias} ${prefilterWhere}`,
+      prefilterParams
+    );
+    const cursorId2 = rows2[0]?.cursorId;
+    if (cursorId2 !== null && cursorId2 !== void 0) {
+      return encodeDeltaCursor(cursorId2);
+    }
+    const streamRows2 = await db.query(
+      `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND parentSpanId IS NULL AND cursorId IS NOT NULL`
+    );
+    return encodeDeltaCursor(streamRows2[0]?.cursorId);
+  }
+  const cteSql = `
+    WITH candidate_roots AS (
+      SELECT traceId, spanId, cursorId
+      FROM span_events AS ${outerAlias}
+      ${prefilterWhere}
+    ),
+    root_spans AS (
+      SELECT reconstructed.*, candidate_roots.cursorId AS anchorCursorId
+      FROM (
+        ${SPAN_RECONSTRUCT_SELECT}
+        WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM candidate_roots)
+        GROUP BY traceId, spanId
+      ) AS reconstructed
+      INNER JOIN candidate_roots USING (traceId, spanId)
+    )
+  `;
+  const rows = await db.query(
+    `${cteSql} SELECT max(anchorCursorId) AS cursorId FROM root_spans ${postAggWhere}`,
+    [...prefilterParams, ...postAggParams]
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND parentSpanId IS NULL AND cursorId IS NOT NULL`
+  );
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getTraceStreamHeadCursor(db) {
+  const streamRows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND parentSpanId IS NULL AND cursorId IS NOT NULL`
+  );
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getBranchDeltaCursor(db, filters) {
+  const filterRecord = filters ?? {};
+  const userSpanType = filterRecord.spanType;
+  const { spanType: _spanType, ...rest } = filterRecord;
+  const { prefilter, postAgg } = partitionAnchorFilters(rest);
+  const { clause: prefilterClause, params: prefilterFilterParams } = buildWhereClause(prefilter);
+  const prefilterParts = [`eventType = 'start'`, `cursorId IS NOT NULL`];
+  let spanTypeParams;
+  if (typeof userSpanType === "string") {
+    prefilterParts.push(`spanType = ?`);
+    spanTypeParams = [userSpanType];
+  } else {
+    prefilterParts.push(`spanType IN (${BRANCH_SPAN_TYPE_PLACEHOLDERS})`);
+    spanTypeParams = [...BRANCH_SPAN_TYPES];
+  }
+  if (prefilterClause) prefilterParts.push(prefilterClause.replace(/^WHERE\s+/i, ""));
+  const prefilterWhere = `WHERE ${prefilterParts.join(" AND ")}`;
+  const prefilterParams = [...spanTypeParams, ...prefilterFilterParams];
+  const outerAlias = "outer_anchor";
+  const { clause: postAggClause, params: postAggParams } = buildWhereClause(postAgg);
+  if (!postAggClause) {
+    const rows2 = await db.query(
+      `SELECT max(cursorId) AS cursorId FROM span_events AS ${outerAlias} ${prefilterWhere}`,
+      prefilterParams
+    );
+    const cursorId2 = rows2[0]?.cursorId;
+    if (cursorId2 !== null && cursorId2 !== void 0) {
+      return encodeDeltaCursor(cursorId2);
+    }
+    const streamRows2 = await db.query(
+      `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND spanType IN (${BRANCH_SPAN_TYPE_PLACEHOLDERS}) AND cursorId IS NOT NULL`,
+      [...BRANCH_SPAN_TYPES]
+    );
+    return encodeDeltaCursor(streamRows2[0]?.cursorId);
+  }
+  const cteSql = `
+    WITH candidate_anchors AS (
+      SELECT traceId, spanId, cursorId
+      FROM span_events AS ${outerAlias}
+      ${prefilterWhere}
+    ),
+    branch_anchors AS (
+      SELECT reconstructed.*, candidate_anchors.cursorId AS anchorCursorId
+      FROM (
+        ${SPAN_RECONSTRUCT_SELECT}
+        WHERE (traceId, spanId) IN (SELECT traceId, spanId FROM candidate_anchors)
+        GROUP BY traceId, spanId
+      ) AS reconstructed
+      INNER JOIN candidate_anchors USING (traceId, spanId)
+    )
+  `;
+  const rows = await db.query(
+    `${cteSql} SELECT max(anchorCursorId) AS cursorId FROM branch_anchors ${postAggClause}`,
+    [...prefilterParams, ...postAggParams]
+  );
+  const cursorId = rows[0]?.cursorId;
+  if (cursorId !== null && cursorId !== void 0) {
+    return encodeDeltaCursor(cursorId);
+  }
+  const streamRows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND spanType IN (${BRANCH_SPAN_TYPE_PLACEHOLDERS}) AND cursorId IS NOT NULL`,
+    [...BRANCH_SPAN_TYPES]
+  );
+  return encodeDeltaCursor(streamRows[0]?.cursorId);
+}
+async function getBranchStreamHeadCursor(db, userSpanType) {
+  if (userSpanType) {
+    const rows2 = await db.query(
+      `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND spanType = ? AND cursorId IS NOT NULL`,
+      [userSpanType]
+    );
+    return encodeDeltaCursor(rows2[0]?.cursorId);
+  }
+  const rows = await db.query(
+    `SELECT max(cursorId) AS cursorId FROM span_events WHERE eventType = 'start' AND spanType IN (${BRANCH_SPAN_TYPE_PLACEHOLDERS}) AND cursorId IS NOT NULL`,
+    [...BRANCH_SPAN_TYPES]
+  );
+  return encodeDeltaCursor(rows[0]?.cursorId);
+}
 
 // src/storage/domains/observability/index.ts
 function buildSignalMigrationRequiredMessage(args) {
@@ -2968,6 +3623,7 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
       });
     }
     await this.db.executeBatch([...ALL_DDL, ...ALL_MIGRATIONS]);
+    await dropLegacyCursorIdDefaults(this.db);
   }
   /**
    * Manually migrate legacy signal tables to the signal-ID primary-key schema.
@@ -3004,6 +3660,12 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
       supported: ["event-sourced"]
     };
   }
+  getFeatures() {
+    if (!deltaPollingFeatureEnabled()) {
+      return void 0;
+    }
+    return ["delta-polling"];
+  }
   // Tracing
   async createSpan(args) {
     return createSpan(this.db, args);
@@ -3140,5 +3802,5 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
 };
 
 export { ObservabilityStorageDuckDB };
-//# sourceMappingURL=observability-TS5QIHIC.js.map
-//# sourceMappingURL=observability-TS5QIHIC.js.map
+//# sourceMappingURL=observability-M35AJUGT.js.map
+//# sourceMappingURL=observability-M35AJUGT.js.map