deepline 0.1.91 → 0.1.94

package/dist/index.mjs

@@ -179,10 +179,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.91",
+  version: "0.1.94",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.91",
+    latest: "0.1.94",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -537,6 +537,807 @@ function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
+// src/stream-reconnect.ts
+var STREAM_RECONNECT_BASE_DELAY_MS = 500;
+var STREAM_RECONNECT_MAX_DELAY_MS = 15e3;
+var STREAM_HEALTHY_CONNECTION_MS = 3e4;
+function streamReconnectDelayMs(attempt) {
+  const cappedExponentialMs = Math.min(
+    STREAM_RECONNECT_MAX_DELAY_MS,
+    STREAM_RECONNECT_BASE_DELAY_MS * 2 ** Math.max(0, attempt)
+  );
+  return Math.max(1, Math.floor(Math.random() * (cappedExponentialMs + 1)));
+}
+function isTransientPlayStreamError(error) {
+  if (error instanceof DeeplineError && typeof error.statusCode === "number") {
+    return error.statusCode >= 500 && error.statusCode < 600;
+  }
+  const text = error instanceof Error ? error.message : String(error);
+  return /auth validation backend timed out|fetch failed|eaddrnotavail|econnreset|etimedout|eai_again|socket hang up/i.test(
+    text
+  );
+}
+
+// ../shared_libs/play-runtime/live-events.ts
+function resolveTimingWindow(input) {
+  const startedAt = typeof input.startedAt === "number" && Number.isFinite(input.startedAt) ? input.startedAt : null;
+  const completedAt = typeof input.completedAt === "number" && Number.isFinite(input.completedAt) ? input.completedAt : null;
+  const updatedAt = typeof input.updatedAt === "number" && Number.isFinite(input.updatedAt) ? input.updatedAt : null;
+  return {
+    startedAt,
+    completedAt,
+    updatedAt
+  };
+}
+
+// ../shared_libs/play-runtime/run-ledger.ts
+var LOG_TAIL_LIMIT = 100;
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function optionalFiniteNumber(value) {
+  const normalized = finiteNumber(value);
+  return normalized === null ? void 0 : normalized;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function optionalNullableString(value) {
+  if (value === null) return null;
+  return optionalString(value);
+}
+function normalizePlayRunLedgerStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  switch (normalized) {
+    case "queued":
+    case "pending":
+      return "queued";
+    case "running":
+    case "started":
+      return "running";
+    case "waiting":
+      return "waiting";
+    case "completed":
+    case "complete":
+    case "succeeded":
+      return "completed";
+    case "failed":
+    case "error":
+      return "failed";
+    case "cancelled":
+    case "canceled":
+      return "cancelled";
+    case "terminated":
+      return "terminated";
+    case "timed_out":
+    case "timeout":
+      return "timed_out";
+    default:
+      return "unknown";
+  }
+}
+function createEmptyPlayRunLedgerSnapshot(input) {
+  const status = normalizePlayRunLedgerStatus(input.status ?? "unknown");
+  const startedAt = finiteNumber(input.startedAt) ?? null;
+  const finishedAt = finiteNumber(input.finishedAt) ?? null;
+  return {
+    runId: input.runId,
+    playName: input.playName ?? null,
+    status,
+    error: optionalNullableString(input.error) ?? null,
+    createdAt: finiteNumber(input.createdAt) ?? null,
+    startedAt,
+    updatedAt: finiteNumber(input.updatedAt) ?? finishedAt ?? startedAt ?? finiteNumber(input.createdAt) ?? null,
+    finishedAt,
+    durationMs: startedAt !== null && finishedAt !== null ? Math.max(0, finishedAt - startedAt) : null,
+    orderedStepIds: [],
+    stepsById: {},
+    logTail: [],
+    totalLogCount: 0,
+    logsTruncated: false,
+    activeStepId: null,
+    activeArtifactTableNamespace: null,
+    resultTableNamespace: null
+  };
+}
+function normalizePlayRunLedgerSnapshot(value, fallback) {
+  if (!isRecord(value)) {
+    return createEmptyPlayRunLedgerSnapshot(fallback);
+  }
+  const orderedStepIds = Array.isArray(value.orderedStepIds) ? value.orderedStepIds.filter(
+    (entry) => typeof entry === "string" && Boolean(entry.trim())
+  ) : [];
+  const rawSteps = isRecord(value.stepsById) ? value.stepsById : {};
+  const stepsById = {};
+  for (const [stepId, rawStep] of Object.entries(rawSteps)) {
+    if (!stepId.trim() || !isRecord(rawStep)) continue;
+    const rawStatus = normalizeStepStatus(rawStep.status);
+    if (!rawStatus) continue;
+    const completedAt = finiteNumber(rawStep.completedAt);
+    const status = rawStatus === "running" && completedAt !== null ? "completed" : rawStatus;
+    const rawProgress = isRecord(rawStep.progress) ? rawStep.progress : null;
+    stepsById[stepId] = {
+      stepId,
+      label: optionalString(rawStep.label),
+      kind: optionalString(rawStep.kind),
+      status,
+      artifactTableNamespace: optionalNullableString(
+        rawStep.artifactTableNamespace
+      ),
+      startedAt: finiteNumber(rawStep.startedAt),
+      completedAt,
+      updatedAt: finiteNumber(rawStep.updatedAt),
+      progress: rawProgress ? normalizeStepProgress(rawProgress) : null
+    };
+  }
+  const createdAt = finiteNumber(value.createdAt) ?? fallback.createdAt ?? null;
+  const startedAt = finiteNumber(value.startedAt) ?? fallback.startedAt ?? null;
+  const finishedAt = finiteNumber(value.finishedAt) ?? fallback.finishedAt ?? null;
+  const updatedAt = finiteNumber(value.updatedAt) ?? fallback.updatedAt ?? finishedAt ?? startedAt ?? createdAt ?? null;
+  const error = Object.prototype.hasOwnProperty.call(value, "error") ? optionalNullableString(value.error) ?? null : fallback.error ?? null;
+  const rawTail = Array.isArray(value.logTail) ? value.logTail : value.logs;
+  const logTail = Array.isArray(rawTail) ? rawTail.filter((line) => typeof line === "string") : [];
+  return {
+    runId: optionalString(value.runId) ?? fallback.runId,
+    playName: optionalNullableString(value.playName) ?? fallback.playName ?? null,
+    status: normalizePlayRunLedgerStatus(value.status ?? fallback.status),
+    error,
+    createdAt,
+    startedAt,
+    updatedAt,
+    finishedAt,
+    durationMs: startedAt !== null && finishedAt !== null ? Math.max(0, finishedAt - startedAt) : finiteNumber(value.durationMs),
+    orderedStepIds: orderedStepIds.filter((stepId) => stepsById[stepId]),
+    stepsById,
+    logTail: logTail.slice(-LOG_TAIL_LIMIT),
+    // Snapshots persisted before totalLogCount existed only know the retained
+    // tail, so the best lower bound for the cumulative count is the tail size.
+    totalLogCount: Math.max(
+      finiteNumber(value.totalLogCount) ?? logTail.length,
+      logTail.length
+    ),
+    logsTruncated: value.logsTruncated === true,
+    activeStepId: optionalNullableString(value.activeStepId),
+    activeArtifactTableNamespace: optionalNullableString(
+      value.activeArtifactTableNamespace
+    ),
+    resultTableNamespace: optionalNullableString(value.resultTableNamespace),
+    resultSummary: value.resultSummary,
+    result: value.result
+  };
+}
+function normalizeStepStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (normalized === "running" || normalized === "completed" || normalized === "failed" || normalized === "skipped") {
+    return normalized;
+  }
+  return null;
+}
+function normalizeStepProgress(value) {
+  return {
+    ...optionalFiniteNumber(value.completed) !== void 0 ? { completed: optionalFiniteNumber(value.completed) } : {},
+    ...optionalFiniteNumber(value.total) !== void 0 ? { total: optionalFiniteNumber(value.total) } : {},
+    ...optionalFiniteNumber(value.failed) !== void 0 ? { failed: optionalFiniteNumber(value.failed) } : {},
+    ...optionalString(value.message) ? { message: optionalString(value.message) } : {},
+    ...optionalNullableString(value.artifactTableNamespace) !== void 0 ? {
+      artifactTableNamespace: optionalNullableString(
+        value.artifactTableNamespace
+      )
+    } : {},
+    ...finiteNumber(value.updatedAt) !== null ? { updatedAt: finiteNumber(value.updatedAt) } : {}
+  };
+}
+
+// ../shared_libs/play-runtime/run-snapshot-stream.ts
+function normalizePlayRunLiveStatus(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  switch (normalized) {
+    case "queued":
+    case "pending":
+      return "running";
+    case "running":
+    case "started":
+      return "running";
+    case "completed":
+    case "complete":
+    case "succeeded":
+      return "completed";
+    case "failed":
+    case "error":
+      return "failed";
+    case "cancelled":
+    case "canceled":
+      return "cancelled";
+    case "terminated":
+      return "terminated";
+    case "timed_out":
+    case "timeout":
+      return "timed_out";
+    default:
+      return "unknown";
+  }
+}
+function isTerminalPlayRunLiveStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled" || status === "terminated" || status === "timed_out";
+}
+function buildSnapshotFromLedger(snapshot) {
+  const nodeStates = snapshot.orderedStepIds.map((stepId) => snapshot.stepsById[stepId]).filter((step) => Boolean(step)).map((step) => ({
+    nodeId: step.stepId,
+    status: step.status,
+    artifactTableNamespace: step.artifactTableNamespace ?? null,
+    progress: step.progress ? {
+      completed: step.progress.completed,
+      total: step.progress.total,
+      failed: step.progress.failed,
+      message: step.progress.message,
+      artifactTableNamespace: step.progress.artifactTableNamespace ?? step.artifactTableNamespace ?? null,
+      startedAt: step.startedAt ?? null,
+      completedAt: step.completedAt ?? null,
+      updatedAt: step.progress.updatedAt ?? step.updatedAt ?? null
+    } : null,
+    startedAt: step.startedAt ?? null,
+    completedAt: step.completedAt ?? null,
+    updatedAt: step.updatedAt ?? null
+  }));
+  return {
+    runId: snapshot.runId,
+    status: normalizePlayRunLiveStatus(snapshot.status),
+    updatedAt: snapshot.updatedAt ?? snapshot.finishedAt ?? snapshot.startedAt ?? null,
+    logs: snapshot.logTail,
+    totalLogCount: snapshot.totalLogCount,
+    ...snapshot.logsTruncated ? { logsTruncated: true } : {},
+    activeArtifactTableNamespace: snapshot.activeArtifactTableNamespace ?? null,
+    resultTableNamespace: snapshot.resultTableNamespace ?? null,
+    nodeStates,
+    activeNodeId: snapshot.activeStepId ?? null
+  };
+}
+function buildPlayRunStatusSnapshot(input) {
+  const ledgerSnapshot = normalizePlayRunLedgerSnapshot(input.run.runSnapshot, {
+    runId: input.run.workflowId,
+    playName: input.run.name ?? null,
+    status: input.run.status,
+    createdAt: input.run.createdAt ?? null,
+    startedAt: input.run.startedAt ?? null,
+    updatedAt: input.run.updatedAt ?? null,
+    finishedAt: input.run.finishedAt ?? null
+  });
+  return buildSnapshotFromLedger(ledgerSnapshot);
+}
+function makeRunStreamEvent(input) {
+  return {
+    ...input,
+    scope: "play",
+    at: input.at ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var EMPTY_PLAY_RUN_STREAM_DIFF_STATE = {
+  runSignature: "",
+  snapshotSignature: "",
+  stepStatusSignature: "",
+  stepProgressSignature: "",
+  lastLogSeq: 0
+};
+function getSnapshotCursor(snapshot) {
+  return String(snapshot.updatedAt ?? Date.now());
+}
+function getRunSignature(snapshot) {
+  return [snapshot.runId, snapshot.status, snapshot.updatedAt ?? 0].join(":");
+}
+function getStepStatusSignature(snapshot) {
+  return snapshot.nodeStates.map(
+    (state) => [
+      state.nodeId,
+      state.status,
+      state.artifactTableNamespace ?? "",
+      state.startedAt ?? "",
+      state.completedAt ?? "",
+      state.progress?.startedAt ?? "",
+      state.progress?.completedAt ?? "",
+      state.updatedAt ?? "",
+      state.progress?.updatedAt ?? ""
+    ].join(":")
+  ).join("|");
+}
+function getStepProgressSignature(snapshot) {
+  return snapshot.nodeStates.map(
+    (state) => [
+      state.nodeId,
+      state.progress?.completed ?? "",
+      state.progress?.total ?? "",
+      state.progress?.failed ?? "",
+      state.progress?.artifactTableNamespace ?? "",
+      state.progress?.startedAt ?? "",
+      state.progress?.completedAt ?? "",
+      state.progress?.updatedAt ?? "",
+      state.progress?.message ?? ""
+    ].join(":")
+  ).join("|");
+}
+function getSnapshotSignature(snapshot) {
+  return JSON.stringify(snapshot);
+}
+function resolvePlayRunLogGap(snapshot, lastLogSeq) {
+  if (snapshot.totalLogCount <= lastLogSeq) {
+    return null;
+  }
+  const tailFirstSeq = snapshot.totalLogCount - snapshot.logs.length + 1;
+  if (lastLogSeq + 1 >= tailFirstSeq) {
+    return null;
+  }
+  return {
+    missingCount: tailFirstSeq - 1 - lastLogSeq,
+    tailFirstSeq
+  };
+}
+function diffLogLines(input) {
+  const { logs, totalLogCount } = input.snapshot;
+  if (totalLogCount <= input.lastLogSeq) {
+    return { lines: [], lastLogSeq: input.lastLogSeq, firstSeq: null };
+  }
+  const tailFirstSeq = totalLogCount - logs.length + 1;
+  if (input.lastLogSeq + 1 >= tailFirstSeq) {
+    return {
+      lines: logs.slice(input.lastLogSeq + 1 - tailFirstSeq),
+      lastLogSeq: totalLogCount,
+      firstSeq: input.lastLogSeq + 1
+    };
+  }
+  const missingCount = tailFirstSeq - 1 - input.lastLogSeq;
+  return {
+    lines: [
+      `[stream] ${missingCount} log lines not retained in the live window; full logs via runs logs`,
+      ...logs
+    ],
+    lastLogSeq: totalLogCount,
+    firstSeq: null
+  };
+}
+function diffPlayRunStreamEvents(input) {
+  const { snapshot, streamId, previous } = input;
+  const cursor = getSnapshotCursor(snapshot);
+  const logDiff = diffLogLines({
+    snapshot,
+    lastLogSeq: previous.lastLogSeq
+  });
+  const next = {
+    runSignature: getRunSignature(snapshot),
+    stepStatusSignature: getStepStatusSignature(snapshot),
+    stepProgressSignature: getStepProgressSignature(snapshot),
+    snapshotSignature: getSnapshotSignature(snapshot),
+    lastLogSeq: logDiff.lastLogSeq
+  };
+  const events = [];
+  if (next.stepStatusSignature !== previous.stepStatusSignature) {
+    for (const state of snapshot.nodeStates) {
+      if (state.status === "idle") {
+        continue;
+      }
+      const persistedStartedAt = state.startedAt ?? state.progress?.startedAt ?? null;
+      const persistedCompletedAt = state.completedAt ?? state.progress?.completedAt ?? null;
+      events.push(
+        makeRunStreamEvent({
+          cursor,
+          streamId,
+          type: "play.step.status",
+          payload: {
+            runId: snapshot.runId,
+            stepId: state.nodeId,
+            status: state.status,
+            artifactTableNamespace: state.artifactTableNamespace ?? null,
+            ...resolveTimingWindow({
+              startedAt: persistedStartedAt,
+              completedAt: persistedCompletedAt,
+              updatedAt: state.updatedAt ?? state.progress?.updatedAt ?? snapshot.updatedAt ?? null
+            })
+          }
+        })
+      );
+    }
+  }
+  if (next.stepProgressSignature !== previous.stepProgressSignature) {
+    for (const state of snapshot.nodeStates) {
+      if (!state.progress) {
+        continue;
+      }
+      events.push(
+        makeRunStreamEvent({
+          cursor: String(
+            state.progress.updatedAt ?? snapshot.updatedAt ?? Date.now()
+          ),
+          streamId,
+          type: "play.step.progress",
+          payload: {
+            runId: snapshot.runId,
+            stepId: state.nodeId,
+            completed: state.progress.completed,
+            total: state.progress.total,
+            failed: state.progress.failed,
+            message: state.progress.message,
+            artifactTableNamespace: state.progress.artifactTableNamespace ?? state.artifactTableNamespace ?? null,
+            ...resolveTimingWindow({
+              startedAt: state.startedAt ?? state.progress.startedAt ?? null,
+              completedAt: state.completedAt ?? state.progress.completedAt ?? null,
+              updatedAt: state.progress.updatedAt ?? snapshot.updatedAt ?? null
+            })
+          }
+        })
+      );
+    }
+  }
+  if (logDiff.lines.length > 0) {
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.log",
+        payload: {
+          runId: snapshot.runId,
+          lines: logDiff.lines,
+          source: "worker",
+          ...logDiff.firstSeq !== null ? { firstSeq: logDiff.firstSeq } : {},
+          totalLogCount: snapshot.totalLogCount
+        }
+      })
+    );
+  }
+  if (next.snapshotSignature !== previous.snapshotSignature) {
+    const enrichedNodeStates = snapshot.nodeStates.map((state) => {
+      const timing = resolveTimingWindow({
+        startedAt: state.startedAt ?? state.progress?.startedAt ?? null,
+        completedAt: state.completedAt ?? state.progress?.completedAt ?? null,
+        updatedAt: state.updatedAt ?? state.progress?.updatedAt ?? snapshot.updatedAt ?? null
+      });
+      return {
+        ...state,
+        ...timing,
+        progress: state.progress ? {
+          ...state.progress,
+          ...resolveTimingWindow({
+            startedAt: state.progress.startedAt ?? state.startedAt ?? null,
+            completedAt: state.progress.completedAt ?? state.completedAt ?? null,
+            updatedAt: state.progress.updatedAt ?? state.updatedAt ?? snapshot.updatedAt ?? null
+          })
+        } : state.progress
+      };
+    });
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.snapshot",
+        payload: { ...snapshot, nodeStates: enrichedNodeStates }
+      })
+    );
+  }
+  if (next.runSignature !== previous.runSignature) {
+    events.push(
+      makeRunStreamEvent({
+        cursor,
+        streamId,
+        type: "play.run.status",
+        payload: {
+          runId: snapshot.runId,
+          status: snapshot.status,
+          updatedAt: snapshot.updatedAt
+        }
+      })
+    );
+  }
+  return { events, next };
+}
+
+// src/runs/observe-transport.ts
+var RunObserveTransportUnavailableError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "RunObserveTransportUnavailableError";
+  }
+  reason;
+};
+var OBSERVE_BOOTSTRAP_TIMEOUT_MS = 1e4;
+var OBSERVE_RECONNECT_NOTICE_MS = 1e4;
+var OBSERVE_STALE_WARNING_MS = 12e4;
+var OBSERVE_WATCHDOG_TICK_MS = 5e3;
+var GRANT_REFRESH_MARGIN_MS = 5 * 6e4;
+var BACKFILL_PAGE_LIMIT = 1e3;
+var BACKFILL_MAX_PAGES = 30;
+var OBSERVER_SNAPSHOT_QUERY = "runObservers:getPlayRunSnapshotForObserver";
+var OBSERVER_LOG_PAGE_QUERY = "runObservers:getRunLogPageForObserver";
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function mintRunObserveGrant(http, runId) {
+  let response;
+  try {
+    response = await http.post(
+      `/api/v2/runs/${encodeURIComponent(runId)}/observe-grant`,
+      {}
+    );
+  } catch (error) {
+    if (error instanceof DeeplineError) {
+      if (error.statusCode === 401 || error.statusCode === 403) {
+        throw error;
+      }
+      throw new RunObserveTransportUnavailableError(
+        `observe-grant endpoint unavailable (${error.statusCode ?? "network"}): ${error.message}`,
+        "grant_endpoint_unavailable"
+      );
+    }
+    throw new RunObserveTransportUnavailableError(
+      `observe-grant request failed: ${errorText(error)}`,
+      "grant_request_failed"
+    );
+  }
+  const grant = response;
+  if (!grant || typeof grant.convexUrl !== "string" || !grant.convexUrl.trim() || typeof grant.token !== "string" || !grant.token.trim() || typeof grant.expiresAt !== "number") {
+    throw new RunObserveTransportUnavailableError(
+      "observe-grant endpoint returned an invalid grant payload.",
+      "grant_payload_invalid"
+    );
+  }
+  return grant;
+}
+async function backfillLogGap(input) {
+  const lines = [];
+  let cursor = input.lastLogSeq;
+  for (let page = 0; page < BACKFILL_MAX_PAGES; page += 1) {
+    if (cursor >= input.tailFirstSeq - 1) {
+      break;
+    }
+    let logPage;
+    try {
+      logPage = await input.queryLogPage(
+        cursor,
+        Math.min(BACKFILL_PAGE_LIMIT, input.tailFirstSeq - 1 - cursor)
+      );
+    } catch {
+      return null;
+    }
+    const entries = (logPage?.entries ?? []).filter(
+      (entry) => entry.seq > cursor && entry.seq < input.tailFirstSeq
+    );
+    if (entries.length === 0) {
+      break;
+    }
+    for (const entry of entries) {
+      if (entry.seq !== cursor + 1) {
+        return null;
+      }
+      lines.push(entry.line);
+      cursor = entry.seq;
+    }
+  }
+  if (cursor < input.tailFirstSeq - 1) {
+    return null;
+  }
+  return lines;
+}
+async function* observeRunEvents(options) {
+  const { http, runId } = options;
+  let grant = await mintRunObserveGrant(http, runId);
+  let convexBrowser;
+  let convexServer;
+  try {
+    convexBrowser = await import("convex/browser");
+    convexServer = await import("convex/server");
+  } catch (error) {
+    throw new RunObserveTransportUnavailableError(
+      `convex client module unavailable: ${errorText(error)}`,
+      "convex_module_unavailable"
+    );
+  }
+  let webSocketConstructor;
+  if (typeof WebSocket === "undefined") {
+    try {
+      const wsModuleName = "ws";
+      const ws = await import(wsModuleName);
+      webSocketConstructor = ws.default;
+    } catch (error) {
+      throw new RunObserveTransportUnavailableError(
+        `no WebSocket implementation available: ${errorText(error)}`,
+        "websocket_unavailable"
+      );
+    }
+  }
+  const snapshotQuery = convexServer.makeFunctionReference(
+    OBSERVER_SNAPSHOT_QUERY
+  );
+  const logPageQuery = convexServer.makeFunctionReference(
+    OBSERVER_LOG_PAGE_QUERY
+  );
+  const client = new convexBrowser.ConvexClient(grant.convexUrl, {
+    ...webSocketConstructor ? { webSocketConstructor } : {},
+    unsavedChangesWarning: false
+  });
+  const queue = [];
+  let wake = null;
+  const push = (item) => {
+    queue.push(item);
+    wake?.();
+    wake = null;
+  };
+  let lastForcedRefreshAt = 0;
+  client.setAuth(async ({ forceRefreshToken }) => {
+    const now = Date.now();
+    if (!forceRefreshToken && grant.expiresAt - now > GRANT_REFRESH_MARGIN_MS) {
+      return grant.token;
+    }
+    if (forceRefreshToken && now - lastForcedRefreshAt < 5e3) {
+      push({
+        kind: "error",
+        error: new DeeplineError(
+          `Run observe grant for ${runId} was rejected after a re-mint. The server and Convex deployment disagree on the grant issuer/JWKS.`,
+          401,
+          "RUN_OBSERVE_GRANT_REJECTED"
+        )
+      });
+      return null;
+    }
+    if (forceRefreshToken) {
+      lastForcedRefreshAt = now;
+    }
+    try {
+      grant = await mintRunObserveGrant(http, runId);
+      return grant.token;
+    } catch (error) {
+      push({ kind: "error", error });
+      return null;
+    }
+  });
+  const unsubscribe = client.onUpdate(
+    snapshotQuery,
+    { workflowId: runId },
+    (run) => push({ kind: "run", run: run ?? null }),
+    (error) => push({ kind: "error", error })
+  );
+  let lastUpdateAt = Date.now();
+  let lastStatusTerminal = false;
+  let disconnectedSince = null;
+  let warnedReconnecting = false;
+  let warnedStale = false;
+  const watchdog = setInterval(() => {
+    const now = Date.now();
+    try {
+      const connectionState = client.connectionState();
+      if (connectionState.isWebSocketConnected) {
+        disconnectedSince = null;
+        warnedReconnecting = false;
+      } else {
+        disconnectedSince ??= now;
+        if (!warnedReconnecting && now - disconnectedSince >= OBSERVE_RECONNECT_NOTICE_MS) {
+          warnedReconnecting = true;
+          options.onNotice?.(
+            `[observe] connection lost; reconnecting to live run ${runId}\u2026`
+          );
+        }
+      }
+    } catch {
+    }
+    if (!lastStatusTerminal && !warnedStale && now - lastUpdateAt >= OBSERVE_STALE_WARNING_MS) {
+      warnedStale = true;
+      options.onNotice?.(
+        `[observe] no live updates for ${Math.round((now - lastUpdateAt) / 1e3)}s; run ${runId} may be stalled (status checks continue)`
+      );
+    }
+  }, OBSERVE_WATCHDOG_TICK_MS);
+  watchdog.unref?.();
+  const abortListener = () => push({
+    kind: "error",
+    error: new DeeplineError(
+      "Run observation aborted.",
+      void 0,
+      "ABORTED"
+    )
+  });
+  options.signal?.addEventListener("abort", abortListener, { once: true });
+  let diffState = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
+  const streamId = ["observe", runId].join(":");
+  let sawFirstSnapshot = false;
+  try {
+    for (; ; ) {
+      if (queue.length === 0) {
+        const waitForItem = new Promise((resolve2) => {
+          wake = resolve2;
+        });
+        if (!sawFirstSnapshot) {
+          const timedOut = await Promise.race([
+            waitForItem.then(() => false),
+            new Promise(
+              (resolve2) => setTimeout(() => resolve2(true), OBSERVE_BOOTSTRAP_TIMEOUT_MS)
+            )
+          ]);
+          if (timedOut && queue.length === 0) {
+            throw new RunObserveTransportUnavailableError(
+              `no snapshot from Convex at ${grant.convexUrl} within ${OBSERVE_BOOTSTRAP_TIMEOUT_MS}ms`,
+              "convex_unreachable"
+            );
+          }
+        } else {
+          await waitForItem;
+        }
+        continue;
+      }
+      const item = queue.shift();
+      if (item.kind === "error") {
+        if (options.signal?.aborted) {
+          return;
+        }
+        throw item.error;
+      }
+      sawFirstSnapshot = true;
+      lastUpdateAt = Date.now();
+      warnedStale = false;
+      if (item.run === null) {
+        throw new DeeplineError(
+          `Run ${runId} was not found (or is not visible to this grant).`,
+          404,
+          "RUN_NOT_FOUND"
+        );
+      }
+      const snapshot = buildPlayRunStatusSnapshot({ run: item.run });
+      lastStatusTerminal = isTerminalPlayRunLiveStatus(snapshot.status);
+      const gap = resolvePlayRunLogGap(snapshot, diffState.lastLogSeq);
+      if (gap && diffState.lastLogSeq > 0) {
+        const backfilled = await backfillLogGap({
+          queryLogPage: (afterSeq, limit) => client.query(logPageQuery, {
+            workflowId: runId,
+            afterSeq,
+            limit
+          }),
+          lastLogSeq: diffState.lastLogSeq,
+          tailFirstSeq: gap.tailFirstSeq
+        });
+        if (backfilled && backfilled.length > 0) {
+          yield {
+            cursor: String(snapshot.updatedAt ?? Date.now()),
+            streamId,
+            scope: "play",
+            type: "play.run.log",
+            at: (/* @__PURE__ */ new Date()).toISOString(),
+            payload: {
+              runId: snapshot.runId,
+              lines: backfilled,
+              source: "worker",
+              firstSeq: diffState.lastLogSeq + 1,
+              totalLogCount: snapshot.totalLogCount
+            }
+          };
+          diffState = { ...diffState, lastLogSeq: gap.tailFirstSeq - 1 };
+        }
+      }
+      const { events, next } = diffPlayRunStreamEvents({
+        streamId,
+        snapshot,
+        previous: diffState
+      });
+      diffState = next;
+      const ordered = [
+        ...events.filter((event) => event.type === "play.run.snapshot"),
+        ...events.filter((event) => event.type !== "play.run.snapshot")
+      ];
+      for (const event of ordered) {
+        yield event;
+      }
+      if (lastStatusTerminal) {
+        return;
+      }
+    }
+  } finally {
+    clearInterval(watchdog);
+    options.signal?.removeEventListener("abort", abortListener);
+    try {
+      unsubscribe();
+    } catch {
+    }
+    await client.close().catch(() => void 0);
+  }
+}
+
 // src/client.ts
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
@@ -555,7 +1356,8 @@ function isTransientCompileManifestError(error) {
     message
   );
 }
-function isRecord(value) {
+var RUN_LOGS_PAGE_LIMIT = 1e3;
+function isRecord2(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPrebuiltPlayDescription(play) {
@@ -625,10 +1427,31 @@ function normalizeLiveStatus(value) {
   }
   return null;
 }
+function appendPlayLiveLogLines(state, payload) {
+  const lines = readStringArray(payload.lines);
+  if (lines.length === 0) {
+    return;
+  }
+  const firstSeq = typeof payload.firstSeq === "number" && Number.isFinite(payload.firstSeq) && payload.firstSeq >= 1 ? Math.trunc(payload.firstSeq) : null;
+  if (firstSeq === null) {
+    state.logs.push(...lines);
+    const totalLogCount = typeof payload.totalLogCount === "number" && Number.isFinite(payload.totalLogCount) ? Math.trunc(payload.totalLogCount) : null;
+    if (totalLogCount !== null) {
+      state.lastLogSeq = Math.max(state.lastLogSeq, totalLogCount);
+    }
+    return;
+  }
+  const skip = Math.max(0, state.lastLogSeq + 1 - firstSeq);
+  if (skip >= lines.length) {
+    return;
+  }
+  state.logs.push(...lines.slice(skip));
+  state.lastLogSeq = Math.max(state.lastLogSeq, firstSeq + lines.length - 1);
+}
 function updatePlayLiveStatusState(state, event) {
   const payload = getPlayLiveEventPayload(event);
   if (event.type === "play.run.log") {
-    state.logs.push(...readStringArray(payload.lines));
+    appendPlayLiveLogLines(state, payload);
     return null;
   }
   if (event.type !== "play.run.snapshot" && event.type !== "play.run.status" && event.type !== "play.run.final_status") {
@@ -636,12 +1459,14 @@ function updatePlayLiveStatusState(state, event) {
   }
   const runId = typeof payload.runId === "string" && payload.runId ? payload.runId : isPlayRunPackage(payload) ? payload.run.id : state.runId;
   const status = normalizeLiveStatus(payload.status) ?? (isPlayRunPackage(payload) ? normalizeLiveStatus(payload.run.status) : null) ?? state.status;
-  const progressPayload = isRecord(payload.progress) ? payload.progress : {};
-  const payloadLogs = readStringArray(payload.logs);
-  const progressLogs = readStringArray(progressPayload.logs);
-  const logs = payloadLogs.length > 0 ? payloadLogs : progressLogs;
-  if (logs.length > 0 || event.type === "play.run.snapshot" || event.type === "play.run.final_status" && !isPlayRunPackage(payload)) {
-    state.logs = logs;
+  const progressPayload = isRecord2(payload.progress) ? payload.progress : {};
+  if (event.type === "play.run.final_status" && state.logs.length === 0 && state.lastLogSeq === 0) {
+    const payloadLogs = readStringArray(payload.logs);
+    const progressLogs = readStringArray(progressPayload.logs);
+    const seedLogs = payloadLogs.length > 0 ? payloadLogs : progressLogs;
+    if (seedLogs.length > 0) {
+      state.logs = seedLogs;
+    }
   }
   if ("result" in payload) {
     state.result = payload.result;
@@ -735,9 +1560,9 @@ var DeeplineClient = class {
     return fields.length > 0 ? { fields } : schema;
   }
   schemaMetadata(schema, key) {
-    if (!isRecord(schema)) return null;
+    if (!isRecord2(schema)) return null;
     const value = schema[key];
-    return isRecord(value) ? value : null;
+    return isRecord2(value) ? value : null;
   }
   playRunCommand(play, options) {
     const target = play.reference || play.name;
@@ -784,7 +1609,7 @@ var DeeplineClient = class {
       aliases,
       inputSchema: options?.compact ? this.compactSchema(play.inputSchema) : play.inputSchema ?? null,
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
-      staticPipeline: isRecord(play.staticPipeline) ? play.staticPipeline : isRecord(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
+      staticPipeline: isRecord2(play.staticPipeline) ? play.staticPipeline : isRecord2(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord2(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand,
@@ -1423,6 +2248,93 @@ var DeeplineClient = class {
     );
     return response.runs ?? [];
   }
+  // ---------------------------------------------------------------------------
+  // Legacy workflows (double-shipped). Thin pass-throughs over the live cloud
+  // `/api/v2/workflows/*` API so the SDK CLI keeps existing cloud workflows
+  // working while users migrate them to plays via `workflows transform`. Kept
+  // intentionally minimal — workflows are a deprecated surface.
+  // ---------------------------------------------------------------------------
+  /** List the org's workflows. `GET /api/v2/workflows`. */
+  async listWorkflows(options) {
+    const params = new URLSearchParams();
+    if (typeof options?.limit === "number") {
+      params.set("limit", String(options.limit));
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return this.http.get(`/api/v2/workflows${query}`);
+  }
+  /**
+   * Fetch a single workflow (including its published-revision config — the
+   * input to `compileWorkflowConfigToPlay`). `GET /api/v2/workflows/:id`.
+   */
+  async getWorkflow(id) {
+    return this.http.get(`/api/v2/workflows/${encodeURIComponent(id)}`);
+  }
+  /** Delete a workflow. `DELETE /api/v2/workflows/:id`. */
+  async deleteWorkflow(id) {
+    return this.http.delete(`/api/v2/workflows/${encodeURIComponent(id)}`);
+  }
+  /** Turn a workflow off. `POST /api/v2/workflows/:id/disable`. */
+  async disableWorkflow(id) {
+    return this.http.post(
+      `/api/v2/workflows/${encodeURIComponent(id)}/disable`,
+      {}
+    );
+  }
+  /** Turn a workflow back on. `POST /api/v2/workflows/:id/enable`. */
+  async enableWorkflow(id) {
+    return this.http.post(
+      `/api/v2/workflows/${encodeURIComponent(id)}/enable`,
+      {}
+    );
+  }
+  /** Create/update a workflow from config. `POST /api/v2/workflows/apply`. */
+  async applyWorkflow(body) {
+    return this.http.post("/api/v2/workflows/apply", body);
+  }
+  /** Validate a workflow config without saving. `POST /api/v2/workflows/lint`. */
+  async lintWorkflow(body) {
+    return this.http.post("/api/v2/workflows/lint", body);
+  }
+  /** Fetch live workflow request schemas. `GET /api/v2/workflows/schema`. */
+  async getWorkflowSchema(subject) {
+    const params = new URLSearchParams();
+    if (subject) params.set("subject", subject);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return this.http.get(`/api/v2/workflows/schema${query}`);
+  }
+  /** Queue a workflow run. `POST /api/v2/workflows/call`. */
+  async callWorkflow(body) {
+    return this.http.post("/api/v2/workflows/call", body);
+  }
+  /** List a workflow's runs. `GET /api/v2/workflows/:id/runs`. */
+  async listWorkflowRuns(id, options) {
+    const params = new URLSearchParams();
+    if (typeof options?.limit === "number") {
+      params.set("limit", String(options.limit));
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return this.http.get(
+      `/api/v2/workflows/${encodeURIComponent(id)}/runs${query}`
+    );
+  }
+  /** Fetch one workflow run. `GET /api/v2/workflows/:id/runs/:runId`. */
+  async getWorkflowRun(id, runId) {
+    return this.http.get(
+      `/api/v2/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(
+        runId
+      )}`
+    );
+  }
+  /** Cancel a workflow run. `POST /api/v2/workflows/:id/runs/:runId/cancel`. */
+  async cancelWorkflowRun(id, runId) {
+    return this.http.post(
+      `/api/v2/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(
+        runId
+      )}/cancel`,
+      {}
+    );
+  }
   /**
    * Get a run by id using the public runs resource model.
    *
@@ -1468,43 +2380,140 @@ var DeeplineClient = class {
     );
     return response.runs ?? [];
   }
-  /** Read the canonical run stream and return the latest run snapshot. */
-  async tailRun(runId, options) {
+  /**
+   * Observe one run's live events through the Convex Run Snapshot
+   * subscription transport (ADR-0008). Yields the same `play.*` event
+   * envelopes as {@link streamPlayRunEvents} and ends after the terminal
+   * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
+   * server cannot serve the transport (older server, unconfigured grants, or
+   * unreachable Convex) — callers fall back to the SSE stream with a notice.
+   */
+  observeRunEvents(runId, options) {
+    return observeRunEvents({
+      http: this.http,
+      runId,
+      signal: options?.signal,
+      onNotice: options?.onNotice
+    });
+  }
+  /**
+   * Tail one run through the subscription transport until terminal, then
+   * return one durable REST status read (the final Run Response Package).
+   */
+  async tailRunViaObserveTransport(runId, options) {
     const state = {
       runId,
       status: "running",
       logs: [],
+      lastLogSeq: 0,
       latest: null
     };
-    let terminal = false;
-    for await (const event of this.streamPlayRunEvents(runId, {
-      mode: "cli",
-      signal: options?.signal
+    for await (const event of this.observeRunEvents(runId, {
+      signal: options?.signal,
+      onNotice: options?.onNotice
     })) {
       const status = updatePlayLiveStatusState(state, event);
-      if (!status) {
+      if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
         continue;
       }
-      terminal = TERMINAL_PLAY_STATUSES.has(status.status);
-      if (terminal) {
-        break;
-      }
-    }
-    if (terminal && state.latest) {
-      return await this.getRunStatus(state.latest.runId || runId).catch(
+      return await this.getRunStatus(status.runId || runId).catch(
         () => state.latest ?? playRunStatusFromState(state)
       );
     }
-    if (state.latest) {
-      return state.latest;
+    if (options?.signal?.aborted) {
+      throw new DeeplineError("Run observation aborted.", void 0, "ABORTED");
+    }
+    const refreshed = await this.getRunStatus(runId);
+    if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+      return refreshed;
     }
     throw new DeeplineError(
-      `Run stream for ${runId} ended before the initial snapshot.`,
+      `Run observation for ${runId} ended before a terminal status.`,
       void 0,
-      "PLAY_RUN_STREAM_EMPTY",
-      { runId }
+      "PLAY_LIVE_STREAM_ENDED"
     );
   }
+  /**
+   * Read the canonical run stream until a terminal run status is observed.
+   *
+   * Tries the Convex Run Snapshot subscription transport first (ADR-0008);
+   * when the server cannot serve it (grant endpoint missing/unconfigured or
+   * Convex unreachable) it falls back — with one `onNotice` message — to the
+   * support-window SSE stream below.
+   *
+   * Server stream windows are finite: they end cleanly at the function
+   * ceiling even while the run keeps executing. A window that ends (cleanly
+   * or via transient network error) without a terminal event triggers one
+   * durable-status re-check followed by a backed-off reconnect, so long runs
+   * tail to completion. Abort via `options.signal` to stop waiting.
+   */
+  async tailRun(runId, options) {
+    try {
+      return await this.tailRunViaObserveTransport(runId, options);
+    } catch (error) {
+      if (!(error instanceof RunObserveTransportUnavailableError)) {
+        throw error;
+      }
+      options?.onNotice?.(
+        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`
+      );
+    }
+    const state = {
+      runId,
+      status: "running",
+      logs: [],
+      lastLogSeq: 0,
+      latest: null
+    };
+    let reconnectAttempt = 0;
+    for (; ; ) {
+      const connectedAt = Date.now();
+      let sawEvent = false;
+      let endedReason = "stream window ended before a terminal event";
+      try {
+        for await (const event of this.streamPlayRunEvents(runId, {
+          mode: "cli",
+          signal: options?.signal
+        })) {
+          sawEvent = true;
+          const status = updatePlayLiveStatusState(state, event);
+          if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
+            continue;
+          }
+          return await this.getRunStatus(status.runId || runId).catch(
+            () => state.latest ?? playRunStatusFromState(state)
+          );
+        }
+      } catch (error) {
+        if (options?.signal?.aborted || !isTransientPlayStreamError(error)) {
+          throw error;
+        }
+        endedReason = error instanceof Error ? error.message : String(error);
+      }
+      let refreshed = null;
+      try {
+        refreshed = await this.getRunStatus(runId);
+      } catch (error) {
+        if (!isTransientPlayStreamError(error)) {
+          throw error;
+        }
+      }
+      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
+        return refreshed;
+      }
+      if (sawEvent || Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS) {
+        reconnectAttempt = 0;
+      }
+      const delayMs = streamReconnectDelayMs(reconnectAttempt);
+      reconnectAttempt += 1;
+      options?.onReconnect?.({
+        attempt: reconnectAttempt,
+        delayMs,
+        reason: endedReason
+      });
+      await sleep2(delayMs);
+    }
+  }
   /**
    * Fetch persisted logs for a run using the public runs resource model.
    *
@@ -1515,19 +2524,40 @@ var DeeplineClient = class {
    * ```
    */
   async getRunLogs(runId, options) {
-    const status = await this.getRunStatus(runId, { full: true });
-    const logs = status.progress?.logs ?? [];
-    const limit = typeof options?.limit === "number" && Number.isFinite(options.limit) ? Math.max(0, Math.trunc(options.limit)) : 200;
-    const entries = logs.slice(Math.max(0, logs.length - limit));
+    const limit = options?.all ? Number.MAX_SAFE_INTEGER : typeof options?.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.trunc(options.limit) : 200;
+    const fetchPage = (afterSeq2, pageLimit) => this.http.get(
+      `/api/v2/runs/${encodeURIComponent(runId)}/logs?afterSeq=${afterSeq2}&limit=${pageLimit}`
+    );
+    const probe = await fetchPage(0, 1);
+    const lastStoredSeq = probe.lastStoredSeq;
+    let afterSeq = options?.all ? 0 : Math.max(0, lastStoredSeq - limit);
+    const entries = [];
+    while (entries.length < limit) {
+      const page = await fetchPage(
+        afterSeq,
+        Math.min(RUN_LOGS_PAGE_LIMIT, limit - entries.length)
+      );
+      if (page.entries.length === 0) {
+        break;
+      }
+      entries.push(...page.entries);
+      afterSeq = page.entries[page.entries.length - 1].seq;
+      if (!page.hasMore) {
+        break;
+      }
+    }
+    const firstSequence = entries.length > 0 ? entries[0].seq : null;
+    const lastSequence = entries.length > 0 ? entries[entries.length - 1].seq : null;
     return {
-      runId: status.runId,
-      totalCount: logs.length,
+      runId: probe.runId,
+      totalCount: probe.totalLogCount,
       returnedCount: entries.length,
-      firstSequence: logs.length === 0 ? null : logs.length - entries.length + 1,
-      lastSequence: logs.length === 0 ? null : logs.length,
-      truncated: logs.length > entries.length,
-      hasMore: logs.length > entries.length,
-      entries
+      firstSequence,
+      lastSequence,
+      truncated: entries.length < probe.totalLogCount,
+      hasMore: lastSequence !== null && lastSequence < lastStoredSeq,
+      entries: entries.map((entry) => entry.line),
+      ...probe.logsTruncated ? { logsTruncated: true } : {}
     };
   }
   /**
@@ -1818,6 +2848,7 @@ var DeeplineClient = class {
       runId: workflowId,
       status: "running",
       logs: [],
+      lastLogSeq: 0,
       latest: null
     };
     if (options?.signal?.aborted) {
@@ -1971,41 +3002,6 @@ function formatPlayBootstrapFinderKindsForSentence() {
 }
 
 // ../shared_libs/play-runtime/email-status.ts
-var DEFAULT_STATUS_MAP = {
-  verified: { status: "valid", verdict: "send", verified: true },
-  valid: { status: "valid", verdict: "send", verified: true },
-  deliverable: { status: "valid", verdict: "send", verified: true },
-  true: { status: "valid", verdict: "send", verified: true },
-  invalid: { status: "invalid", verdict: "drop", verified: false },
-  undeliverable: { status: "invalid", verdict: "drop", verified: false },
-  false: { status: "invalid", verdict: "drop", verified: false },
-  "catch-all": {
-    status: "catch_all",
-    verdict: "verify_next",
-    verified: false
-  },
-  catch_all: {
-    status: "catch_all",
-    verdict: "verify_next",
-    verified: false
-  },
-  valid_catch_all: {
-    status: "valid_catch_all",
-    verdict: "send_with_caution",
-    verified: true
-  },
-  accept_all: {
-    status: "catch_all",
-    verdict: "verify_next",
-    verified: false
-  },
-  unknown: { status: "unknown", verdict: "hold", verified: false },
-  unavailable: { status: "unknown", verdict: "hold", verified: false },
-  do_not_mail: { status: "do_not_mail", verdict: "drop", verified: false },
-  spamtrap: { status: "spamtrap", verdict: "drop", verified: false },
-  abuse: { status: "abuse", verdict: "drop", verified: false },
-  disposable: { status: "disposable", verdict: "drop", verified: false }
-};
 function normalizeKey(value) {
   if (value == null) return null;
   if (typeof value === "boolean") return String(value);
@@ -2054,7 +3050,7 @@ function mxClass(mxProvider, mxRecord) {
 }
 function entryForStatus(key, map) {
   if (!key) return null;
-  return map?.[key] ?? DEFAULT_STATUS_MAP[key] ?? null;
+  return map?.[key] ?? null;
 }
 function read(values, name) {
   return values[name];
@@ -2188,7 +3184,7 @@ var TARGET_FALLBACK_KEYS = {
   status: [/^email_status$/i, /^status$/i],
   email_status: [/^email_status$/i, /^status$/i]
 };
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function toV2RawToolOutputPath(path) {
@@ -2248,7 +3244,7 @@ function valuesAtSegments(current, segments, path = []) {
     if (!Array.isArray(current)) return [];
     return valuesAtSegments(current[segment], rest, [...path, segment]);
   }
-  if (!isRecord2(current)) return [];
+  if (!isRecord3(current)) return [];
   const directMatches = valuesAtSegments(current[segment], rest, [
     ...path,
     segment
@@ -2278,7 +3274,7 @@ function getValuesAtPath(root, path) {
   return valuesAtSegments(root, parsePath(path)).map((entry) => entry.value);
 }
 function toResultEnvelope(value) {
-  if (isRecord2(value) && "data" in value) {
+  if (isRecord3(value) && "data" in value) {
     const envelope = { data: value.data };
     if ("meta" in value) envelope.meta = value.meta;
     return envelope;
@@ -2331,7 +3327,7 @@ function getAtPath(root, path) {
       current = current[segment];
       continue;
     }
-    if (!isRecord2(current)) return void 0;
+    if (!isRecord3(current)) return void 0;
     current = current[segment];
   }
   return current;
@@ -2348,7 +3344,7 @@ function normalizeString(value) {
 }
 function normalizeRows(value) {
   if (!Array.isArray(value)) return null;
-  return value.map((entry) => isRecord2(entry) ? entry : { value: entry });
+  return value.map((entry) => isRecord3(entry) ? entry : { value: entry });
 }
 function findFirstTargetByPath(result, paths) {
   for (const path of paths ?? []) {
@@ -2407,7 +3403,7 @@ function findFirstTargetByKey(result, target, depth = 0, path = []) {
     }
     return null;
   }
-  if (!isRecord2(result)) return null;
+  if (!isRecord3(result)) return null;
   const patterns = TARGET_FALLBACK_KEYS[target] ?? [
     new RegExp(`^${target}$`, "i")
   ];
@@ -2467,7 +3463,7 @@ function normalizeJobChangeStatus(value) {
 function firstExperienceDate(value) {
   if (!Array.isArray(value)) return null;
   for (const entry of value) {
-    if (!isRecord2(entry)) continue;
+    if (!isRecord3(entry)) continue;
     const date = normalizeString(
       entry.start_date ?? entry.started_at ?? entry.startDate
     );
@@ -2476,10 +3472,10 @@ function firstExperienceDate(value) {
   return null;
 }
 function normalizeJobChange(value) {
-  const record = isRecord2(value) ? value : {};
-  const nested = isRecord2(record.job_change) ? record.job_change : record;
-  const output = isRecord2(nested.output) ? nested.output : nested;
-  const person = isRecord2(output.person) ? output.person : {};
+  const record = isRecord3(value) ? value : {};
+  const nested = isRecord3(record.job_change) ? record.job_change : record;
+  const output = isRecord3(nested.output) ? nested.output : nested;
+  const person = isRecord3(output.person) ? output.person : {};
   const status = normalizeJobChangeStatus(
     output.status ?? output.job_change_status ?? output.job_changed ?? output.changed
   );
@@ -3047,11 +4043,11 @@ var Deepline = class {
     return new DeeplineContext(options);
   }
 };
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function stringArrayRecord(value) {
-  if (!isRecord3(value)) return {};
+  if (!isRecord4(value)) return {};
   return Object.fromEntries(
     Object.entries(value).map(([key, paths]) => [
       key,
@@ -3062,22 +4058,60 @@ function stringArrayRecord(value) {
 function stringArray(value) {
   return Array.isArray(value) ? value.map(String) : [];
 }
+function emailStatusExtractorConfig(value) {
+  if (!isRecord4(value)) return void 0;
+  const readPaths = (key) => {
+    const paths = stringArray(value[key]).map((path) => path.trim()).filter(Boolean);
+    return paths.length > 0 ? paths : void 0;
+  };
+  const provider = typeof value.provider === "string" && value.provider.trim() ? value.provider.trim() : null;
+  if (!provider) return void 0;
+  const config = { provider };
+  for (const key of [
+    "rawStatus",
+    "rawScore",
+    "valid",
+    "deliverability",
+    "catchAll",
+    "mxProvider",
+    "mxRecord",
+    "fraudScore",
+    "disposable",
+    "roleBased",
+    "freeEmail",
+    "abuse",
+    "spamtrap",
+    "suspect"
+  ]) {
+    const paths = readPaths(key);
+    if (paths) config[key] = paths;
+  }
+  if (isRecord4(value.statusMap)) {
+    config.statusMap = value.statusMap;
+  }
+  if (Array.isArray(value.rules)) {
+    config.rules = value.rules;
+  }
+  return config;
+}
 function extractorDescriptorRecord(value) {
-  if (!isRecord3(value)) return {};
+  if (!isRecord4(value)) return {};
   return Object.fromEntries(
     Object.entries(value).flatMap(([key, descriptor]) => {
-      if (!isRecord3(descriptor)) return [];
+      if (!isRecord4(descriptor)) return [];
       const paths = stringArray(descriptor.paths).map((path) => path.trim()).filter(Boolean);
       if (paths.length === 0) return [];
       const transforms = stringArray(descriptor.transforms).map((transform) => transform.trim()).filter(Boolean);
       const enumValues = stringArray(descriptor.enum).map((entry) => entry.trim()).filter(Boolean);
+      const emailStatus = emailStatusExtractorConfig(descriptor.emailStatus);
       return [
         [
           key,
           {
             paths,
             ...transforms.length > 0 ? { transforms } : {},
-            ...enumValues.length > 0 ? { enum: enumValues } : {}
+            ...enumValues.length > 0 ? { enum: enumValues } : {},
+            ...emailStatus ? { emailStatus } : {}
           }
         ]
       ];
@@ -3087,14 +4121,14 @@ function extractorDescriptorRecord(value) {
 function toolExecutionEnvelopeToResult(fallbackToolId, response) {
   const raw = response.toolResponse?.raw ?? null;
   const meta = response.toolResponse?.meta;
-  const metadata = isRecord3(response._metadata) ? response._metadata.tool : null;
-  const toolMetadata = isRecord3(metadata) ? metadata : {};
+  const metadata = isRecord4(response._metadata) ? response._metadata.tool : null;
+  const toolMetadata = isRecord4(metadata) ? metadata : {};
   return createToolExecuteResult({
     status: typeof response.status === "string" ? response.status : "completed",
     jobId: typeof response.job_id === "string" ? response.job_id : void 0,
     result: {
       data: raw,
-      ...isRecord3(meta) ? { meta } : {}
+      ...isRecord4(meta) ? { meta } : {}
     },
     metadata: {
       toolId: typeof toolMetadata.toolId === "string" ? toolMetadata.toolId : fallbackToolId,
@@ -3108,7 +4142,7 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response) {
       cached: false,
       source: "live"
     },
-    meta: isRecord3(response.meta) ? response.meta : void 0
+    meta: isRecord4(response.meta) ? response.meta : void 0
   });
 }
 function defineInput(schema) {
@@ -3409,6 +4443,7 @@ export {
   PLAY_BOOTSTRAP_TEMPLATES,
   PROD_URL,
   RateLimitError,
+  RunObserveTransportUnavailableError,
   SDK_API_CONTRACT,
   SDK_VERSION,
   defineInput,