deepline 0.3.141 → 0.3.143

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.141',
+  version: '0.3.143',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/types.ts

@@ -193,9 +193,9 @@ export type {
  *
  * Returned by {@link DeeplineClient.listTools} and ranked tool search. Use
  * `getTool(toolId)` or the matching HTTP describe route for provider-specific
- * schema, examples, pricing, and extraction guidance before executing.
+ * schema, examples, pricing, extraction guidance, and execution metadata.
  */
-export interface ToolDefinition {
+export interface ToolDefinition extends ToolExecutionMetadataFields {
   /** Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). */
   toolId: string;
   /** Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). */
@@ -345,6 +345,45 @@ export interface ToolDefinition {
   connectionMessage?: string;
 }
 
+export type ToolBatchCapability = {
+  status: 'compiled' | 'exposed_uncompiled' | 'upstream_only';
+  surface: 'registry' | 'local' | 'docs';
+  batchKind: 'identifier_batch' | 'query_share' | 'async_dataset_job';
+  batchOperation: string | null;
+  maxBatchSize: number | null;
+  notes: string;
+};
+
+/** Optional batching, pacing, and configured rate metadata for tool catalog entries. */
+export interface ToolExecutionMetadataFields {
+  batchCapability?: ToolBatchCapability;
+  batch_capability?: ToolBatchCapability;
+  executionMetadata?: ToolExecutionMetadata;
+  execution_metadata?: ToolExecutionMetadata;
+}
+
+export type ToolExecutionMetadata = {
+  provider: string;
+  sourceOperation: string;
+  effectiveOperation: string;
+  batch: {
+    batchOperation: string | null;
+    maxBatchSize: number;
+  };
+  configuredRateLimits: Array<{
+    source: 'deepline_configuration';
+    scope: string;
+    requestsPerWindow: number;
+    windowMs: number;
+    usage: 'queue_hint' | 'enforced' | 'queue_hint_and_enforced' | 'disabled';
+    explicitMaxConcurrency: number | null;
+  }>;
+  queueHint: {
+    requestsPerSecondHint: number;
+    derivedConcurrency: number;
+  };
+};
+
 export interface ModelProviderOptionField {
   name: string;
   type: 'string' | 'number' | 'boolean' | 'object' | 'array';
@@ -697,6 +736,11 @@ export interface PlayRunPackage {
     startedAt?: number | null;
     finishedAt?: number | null;
     durationMs?: number | null;
+    outcome?: PlayRunOutcome;
+    recovery?: {
+      mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+      sourceRunId?: string;
+    };
     error?: string;
     /** Canonical explanation of what this run is doing or waiting on. */
     activity?: PlayRunActivityProjection | null;
@@ -742,6 +786,19 @@ export interface PlayRunPackage {
   };
 }
 
+/**
+ * Stable classification of whether this run executed work or reused/recovered
+ * an existing durable run outcome.
+ */
+export type PlayRunOutcome =
+  | 'executed'
+  | 'reused'
+  | 'joined'
+  | 'recovered'
+  | 'forced'
+  | 'waiting'
+  | 'failed';
+
 /**
  * Current status of a play execution, returned by {@link DeeplineClient.getPlayStatus}.
  *
@@ -779,6 +836,12 @@ export interface PlayStatus {
     | 'completed'
     | 'failed'
     | 'cancelled';
+  /** How this run was admitted or recovered, when the server can prove it. */
+  outcome?: PlayRunOutcome;
+  recovery?: {
+    mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+    sourceRunId?: string;
+  };
   /** Execution progress with logs and error details. */
   progress?: PlayProgressStatus;
   /** Partial or final result. Available once the play returns. */

package/dist/bundling-sources/shared_libs/observability/dlq.ts

@@ -277,6 +277,8 @@ export type QueueItem = {
   readonly editableFields: readonly FieldDefinition[];
   readonly createdAt?: string;
   readonly updatedAt?: string;
+  /** Native failure timestamp when the owner can provide it. */
+  readonly failedAt?: string;
   readonly summary?: string;
   readonly retiredAt?: string;
   readonly retirementReason?: string;
@@ -328,6 +330,18 @@ export type QueueItemUnavailable = {
   readonly reason: string;
 };
 
+/** Server attestation that an item page came from the owner's bounded,
+ * indexed failed-time reader rather than the generic item listing. */
+export type QueueItemFailedTimeRange = {
+  readonly kind: 'failed-time-range';
+  readonly after: string | null;
+  readonly before: string;
+  readonly index: string;
+  readonly indexed: true;
+  /** Stable across every page in the same cursor-bound plan. */
+  readonly snapshotAt: string;
+};
+
 export type QueueItemList = {
   readonly contractVersion: typeof QUEUE_ITEM_CONTROL_CONTRACT_VERSION;
   readonly queueId: string;
@@ -337,6 +351,8 @@ export type QueueItemList = {
   readonly nextCursor: string | null;
   readonly limit: number;
   readonly cursor: string | null;
+  /** Present only for a successfully measured indexed failure-time range. */
+  readonly failedTimeRange?: QueueItemFailedTimeRange;
   readonly unavailable?: QueueItemUnavailable;
 };
 
@@ -445,6 +461,14 @@ export type QueueItemConnector = {
   readonly source: string;
   readonly mapNativeState: (nativeState: string) => QueueItemState;
   readonly list: (context: QueueItemConnectorContext) => Promise<QueueItemList>;
+  /** Optional source-indexed failure-window listing for safe, bounded
+   * retirement planning. The lower bound is inclusive and the upper bound is
+   * exclusive. Connectors must not emulate this by scanning their ordinary
+   * item listing; unsupported sources leave the capability absent. */
+  readonly listFailedInRange?: (
+    context: QueueItemConnectorContext,
+    range: { after?: string; before: string },
+  ) => Promise<QueueItemList>;
   readonly get: (
     context: QueueItemConnectorContext,
     itemId: string,
@@ -470,6 +494,7 @@ export function normalizeQueueItemState(nativeState: string): QueueItemState {
     return 'running';
   }
   if (
+    state === 'failed' ||
     state === 'dead_lettered' ||
     state === 'dead-lettered' ||
     state === 'dlq'

package/dist/bundling-sources/shared_libs/observability/queue-health.ts

@@ -363,6 +363,117 @@ export type QueueObservation = {
   readonly adapter: string;
 };
 
+export type QueueRetirementCandidate = {
+  readonly itemId: string;
+  readonly bucket: 'blocked' | 'deadLettered';
+  readonly ageMs: number;
+};
+
+/**
+ * Remove operator-retired identities from a bounded source sample. The source
+ * still owns every row; the disposition overlay only changes what operators
+ * count as unresolved. Truncated samples remain lower bounds after filtering.
+ */
+export function excludeRetiredQueueCandidates(input: {
+  observation: QueueObservation;
+  candidates: readonly QueueRetirementCandidate[];
+  retiredItemIds: ReadonlySet<string>;
+  truncatedBuckets?: ReadonlySet<QueueRetirementCandidate['bucket']>;
+}): QueueObservation {
+  const {
+    observation,
+    candidates,
+    retiredItemIds,
+    truncatedBuckets = new Set(),
+  } = input;
+  const blocked = candidates.filter(
+    (candidate) => candidate.bucket === 'blocked',
+  );
+  const deadLettered = candidates.filter(
+    (candidate) => candidate.bucket === 'deadLettered',
+  );
+  const adjustDepth = (
+    bucket: 'blocked' | 'deadLettered',
+    rows: readonly QueueRetirementCandidate[],
+  ): Measured<number> => {
+    const measured = observation.depth[bucket];
+    if (measured.kind !== 'exact' && measured.kind !== 'lower_bound') {
+      return measured;
+    }
+    const activeSampleCount = rows.reduce(
+      (count, row) => count + Number(!retiredItemIds.has(row.itemId)),
+      0,
+    );
+    if (
+      measured.kind === 'lower_bound' ||
+      truncatedBuckets.has(bucket) ||
+      rows.length !== measured.value
+    ) {
+      // For a partial source sample, only surviving sampled identities are a
+      // proven lower bound. Subtracting sampled retirements from the source's
+      // lower bound could overstate active work if unseen rows are retired too.
+      return { kind: 'lower_bound', value: activeSampleCount };
+    }
+    return { kind: 'exact', value: activeSampleCount };
+  };
+  const adjustAge = (
+    bucket: 'blocked' | 'deadLettered',
+    rows: readonly QueueRetirementCandidate[],
+    depth: Measured<number>,
+  ): Measured<number> => {
+    const measured = observation.oldestAgeMs[bucket];
+    if (measured.kind !== 'exact' && measured.kind !== 'lower_bound') {
+      return measured;
+    }
+    if (depth.kind === 'unavailable') {
+      return {
+        kind: 'unavailable',
+        reason: `retirement candidate coverage is incomplete for ${bucket}`,
+      };
+    }
+    const remaining = rows.filter((row) => !retiredItemIds.has(row.itemId));
+    if (remaining.length > 0) {
+      const value = Math.max(...remaining.map((row) => row.ageMs));
+      return measured.kind === 'lower_bound' ||
+        truncatedBuckets.has(bucket) ||
+        depth.kind === 'lower_bound'
+        ? { kind: 'lower_bound', value }
+        : { kind: 'exact', value };
+    }
+    if (
+      measured.kind === 'exact' &&
+      depth.kind === 'exact' &&
+      depth.value === 0
+    ) {
+      return { kind: 'not_applicable', reason: 'no work in this bucket' };
+    }
+    if (
+      measured.kind === 'lower_bound' ||
+      truncatedBuckets.has(bucket) ||
+      depth.kind === 'lower_bound'
+    ) {
+      // The bounded source page may have unseen, non-retired rows.
+      return { kind: 'lower_bound', value: 0 };
+    }
+    return measured;
+  };
+  const blockedDepth = adjustDepth('blocked', blocked);
+  const deadLetteredDepth = adjustDepth('deadLettered', deadLettered);
+  return {
+    ...observation,
+    depth: {
+      ...observation.depth,
+      blocked: blockedDepth,
+      deadLettered: deadLetteredDepth,
+    },
+    oldestAgeMs: {
+      ...observation.oldestAgeMs,
+      blocked: adjustAge('blocked', blocked, blockedDepth),
+      deadLettered: adjustAge('deadLettered', deadLettered, deadLetteredDepth),
+    },
+  };
+}
+
 function combineMeasurements(
   observations: readonly QueueObservation[],
   select: (observation: QueueObservation) => Measured<number>,

package/dist/bundling-sources/shared_libs/play-runtime/bettercontact-batching.ts

@@ -321,14 +321,23 @@ function rowMatchesCorrelation(
   correlationField: string,
   correlationValue: string,
 ): boolean {
-  return resultCustomFieldRecords(row).some(
-    (fields) => fields[correlationField] === correlationValue,
-  );
+  const matches = resultCustomFieldRecords(row).filter(
+    (fields) =>
+      fields[correlationField] === correlationValue ||
+      (fields.name === correlationField && fields.value === correlationValue),
+  ).length;
+  if (matches > 1) {
+    throw new Error(
+      'BetterContact scoped result has ambiguous correlation identity.',
+    );
+  }
+  return matches === 1;
 }
 
 function withoutCorrelationSelector(
   row: unknown,
   correlationField: string,
+  correlationValue: string,
 ): unknown {
   if (!row || typeof row !== 'object' || Array.isArray(row)) {
     return row;
@@ -337,7 +346,9 @@ function withoutCorrelationSelector(
   const customFields = record.custom_fields;
   const cleanRecord = (fields: Record<string, unknown>) => {
     const cleaned = { ...fields };
-    delete cleaned[correlationField];
+    if (cleaned[correlationField] === correlationValue) {
+      delete cleaned[correlationField];
+    }
     return cleaned;
   };
   return {
@@ -345,6 +356,11 @@ function withoutCorrelationSelector(
     custom_fields: Array.isArray(customFields)
       ? customFields
           .filter(isPlainRecord)
+          .filter(
+            (fields) =>
+              fields.name !== correlationField ||
+              fields.value !== correlationValue,
+          )
           .map(cleanRecord)
           .filter((fields) => Object.keys(fields).length > 0)
       : isPlainRecord(customFields)
@@ -381,7 +397,13 @@ export function isolateBetterContactScopedResult(
   }
   return {
     ...scopedResult,
-    data: [withoutCorrelationSelector(matches[0], scope.correlationField)],
+    data: [
+      withoutCorrelationSelector(
+        matches[0],
+        scope.correlationField,
+        scope.correlationValue,
+      ),
+    ],
   };
 }
 
@@ -417,11 +439,15 @@ function withoutCorrelationField(
   if (!row || typeof row !== 'object' || Array.isArray(row)) {
     return row;
   }
-  const correlationField = correlationEntryForItem(item)?.[0];
-  if (!correlationField) {
+  const correlationEntry = correlationEntryForItem(item);
+  if (!correlationEntry) {
     return row;
   }
-  return withoutCorrelationSelector(row, correlationField);
+  return withoutCorrelationSelector(
+    row,
+    correlationEntry[0],
+    String(correlationEntry[1]),
+  );
 }
 
 function scopedRequestIdForItem(