deepline 0.3.372 → 0.3.374

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.372',
+  version: '0.3.374',
   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/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts

@@ -28,7 +28,6 @@ import {
   RUNTIME_SANDBOX_MEMORY_ABORT_CODE,
   RUNTIME_SANDBOX_MEMORY_ABORT_MESSAGE,
   RUNTIME_SANDBOX_OOM_MESSAGE,
-  RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE,
 } from '../../run-failure';
 import {
   buildDaytonaPayloadMaterializerSource,
@@ -295,41 +294,6 @@ function watchdogMemoryAbortDiagnostic() {
   return null;
 }
 
-function watchdogRunnerHeartbeatUnavailableDiagnostic() {
-  try {
-    if (!terminationDiagnosticPath) return null;
-    const diagnostic = JSON.parse(
-      fs.readFileSync(terminationDiagnosticPath, 'utf8'),
-    );
-    if (
-      !diagnostic ||
-      diagnostic.schemaVersion !== 1 ||
-      diagnostic.reason !== 'runner_heartbeat_unreachable'
-    ) {
-      return null;
-    }
-    return {
-      heartbeatAttempt: Number.isSafeInteger(diagnostic.heartbeatAttempt)
-        ? diagnostic.heartbeatAttempt
-        : null,
-      heartbeatAgeMs: Number.isFinite(diagnostic.heartbeatAgeMs)
-        ? Math.max(0, diagnostic.heartbeatAgeMs)
-        : null,
-      leaseMs: Number.isFinite(diagnostic.leaseMs)
-        ? Math.max(0, diagnostic.leaseMs)
-        : null,
-      lastErrorCode:
-        typeof diagnostic.lastErrorCode === 'string' &&
-        /^(?:E[A-Z0-9_]+|ERR_[A-Z0-9_]+|UND_ERR_[A-Z0-9_]+|TimeoutError|redirect_[0-9]{3}|http_[0-9]{3}|protocol_error|unknown)$/.test(
-          diagnostic.lastErrorCode,
-        )
-          ? diagnostic.lastErrorCode
-          : 'unknown',
-    };
-  } catch {}
-  return null;
-}
-
 function memoryAbortCause(diagnostic) {
   const parts = [
     ${JSON.stringify(`${RUNTIME_SANDBOX_MEMORY_ABORT_CODE}: ${RUNTIME_SANDBOX_MEMORY_ABORT_MESSAGE}`)},
@@ -411,7 +375,6 @@ async function main() {
   // SIGKILL does not collapse into the wrapper's generic exit code 1.
   const sandboxKilled = exitCode === 137 || watchdogObservedChildSigkill();
   const memoryAbort = watchdogMemoryAbortDiagnostic();
-  const heartbeatUnavailable = watchdogRunnerHeartbeatUnavailableDiagnostic();
   const sandboxOom =
     !memoryAbort &&
     sandboxKilled &&
@@ -422,10 +385,6 @@ async function main() {
       ? memoryAbortCause(memoryAbort)
     : sandboxOom
       ? 'RUNTIME_SANDBOX_OOM: ' + ${JSON.stringify(RUNTIME_SANDBOX_OOM_MESSAGE)}
-    : heartbeatUnavailable
-      ? 'RUNTIME_CONTROL_PLANE_UNAVAILABLE: ' +
-        ${JSON.stringify(RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE)} +
-        ' heartbeat=' + JSON.stringify(heartbeatUnavailable)
       : sandboxKilled
         ? 'RUNTIME_SANDBOX_KILLED: ' + ${JSON.stringify(RUNTIME_SANDBOX_KILLED_MESSAGE)}
     :
@@ -453,15 +412,6 @@ async function main() {
           cause: synthesizedError,
       }] }
       : {}),
-    ...(heartbeatUnavailable && !runtimeLimitExceeded && !memoryAbort && !sandboxOom
-      ? { errors: [{
-          code: 'RUNTIME_CONTROL_PLANE_UNAVAILABLE',
-          phase: 'infrastructure',
-          message: ${JSON.stringify(RUNTIME_CONTROL_PLANE_UNAVAILABLE_MESSAGE)},
-          retryable: false,
-          cause: synthesizedError,
-        }] }
-      : {}),
     ...(sandboxOom
       ? { errors: [{
           code: 'RUNTIME_SANDBOX_OOM',
@@ -480,9 +430,7 @@ async function main() {
           cause: synthesizedError,
         }] }
       : {}),
-    logs: heartbeatUnavailable
-      ? ['[runtime.failure_diagnostic] ' + JSON.stringify({ event: 'runner_heartbeat_unavailable', ...heartbeatUnavailable })]
-      : [],
+    logs: [],
     stats: {},
     steps: [],
     checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.ABSENT}',

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-runtime-watchdog.ts

@@ -196,8 +196,6 @@ let heartbeatConfigRead = false;
 let heartbeatConfig = null;
 let heartbeatLastSuccessAtMs = 0;
 let heartbeatAttempt = 0;
-let heartbeatLastErrorCode = null;
-let heartbeatStopBeforeLeaseMs = 0;
 let stopRequested = false;
 
 function readRunnerHeartbeatConfig() {
@@ -246,7 +244,7 @@ function stopRunnerHeartbeat() {
 
 function runnerHeartbeatErrorCode(error) {
   const code = error && typeof error.code === 'string' ? error.code : '';
-  if (/^(?:E[A-Z0-9_]+|ERR_[A-Z0-9_]+|UND_ERR_[A-Z0-9_]+)$/.test(code)) return code;
+  if (/^(?:E[A-Z0-9_]+|ERR_[A-Z0-9_]+|UND_ERR_[A-Z0-9_]+|http_[0-9]{3}|redirect_[0-9]{3}|protocol_error)$/.test(code)) return code;
   const name = error && typeof error.name === 'string' ? error.name : '';
   if (name === 'AbortError' || name === 'TimeoutError') return name;
   return 'unknown';
@@ -263,10 +261,6 @@ function startRunnerHeartbeatSupervisor() {
   const handoffAt = Number(handoff && handoff.lastHeartbeatAtMs);
   heartbeatLastSuccessAtMs = Number.isFinite(handoffAt) ? handoffAt : Date.now();
   const cadenceMs = Math.max(250, Math.floor(config.leaseMs / ${RUNTIME_CLAIM_HEARTBEAT_DIVISOR}));
-  heartbeatStopBeforeLeaseMs = Math.max(
-    0,
-    config.leaseMs - cadenceMs - ${RUNNER_HEARTBEAT_REQUEST_TIMEOUT_MS},
-  );
   process.stderr.write(
     '[play-runner.heartbeat] watchdog_owner_started ' +
       JSON.stringify({ runId: config.runId, cadenceMs, handoffHeartbeatAgeMs: Math.max(0, Date.now() - heartbeatLastSuccessAtMs) }) +
@@ -325,35 +319,33 @@ async function runnerHeartbeatTick() {
       throw Object.assign(new Error('gateway_protocol_error'), { code: 'protocol_error' });
     }
     heartbeatLastSuccessAtMs = Date.now();
-    heartbeatLastErrorCode = null;
   } catch (error) {
     if (heartbeatStopped || settled) return;
-    heartbeatLastErrorCode = controller.signal.aborted
+    const errorCode = controller.signal.aborted
       ? 'TimeoutError'
       : runnerHeartbeatErrorCode(error);
     const heartbeatAgeMs = Math.max(0, Date.now() - heartbeatLastSuccessAtMs);
     process.stderr.write(
       '[play-runner.heartbeat] watchdog_owner_retrying ' +
-        JSON.stringify({ runId: config.runId, attempt: heartbeatAttempt, durationMs: Math.max(0, Date.now() - startedAt), heartbeatAgeMs, errorCode: heartbeatLastErrorCode }) +
+        JSON.stringify({ runId: config.runId, attempt: heartbeatAttempt, durationMs: Math.max(0, Date.now() - startedAt), heartbeatAgeMs, errorCode }) +
         '\\n',
     );
-    // Stop before the scheduler's lease expires. A failed request can consume
-    // its full timeout, and the next cadence would otherwise let the scheduler
-    // win the terminal race and report an ambiguous runner loss.
-    if (heartbeatAgeMs >= heartbeatStopBeforeLeaseMs) {
+    // The gateway answered definitively: this token is invalid (401), out of
+    // scope (403), or its attempt is no longer the run's current one (404).
+    // Nothing else stops a superseded attempt's paid calls, so stop now.
+    const rejection = /^http_(401|403|404)$/.exec(errorCode);
+    if (rejection) {
       stopRunnerHeartbeat();
-      const diagnostic = {
-        heartbeatAttempt,
-        heartbeatAgeMs,
-        leaseMs: config.leaseMs,
-        stopBeforeLeaseMs: heartbeatStopBeforeLeaseMs,
-        lastErrorCode: heartbeatLastErrorCode,
-      };
+      const diagnostic = { heartbeatAttempt, status: Number(rejection[1]) };
       process.stderr.write(
-        'RUNTIME_CONTROL_PLANE_UNAVAILABLE: ' + JSON.stringify(diagnostic) + '\\n',
+        '[play-runner.heartbeat] watchdog_owner_rejected ' + JSON.stringify(diagnostic) + '\\n',
       );
-      stopChild('runner_heartbeat_unreachable', diagnostic);
+      stopChild('runner_heartbeat_rejected', diagnostic);
     }
+    // Otherwise keep renewing. An unreachable or failing control plane is not
+    // evidence that this run is over: the scheduler owns the liveness verdict
+    // and confirms it only after it can accept heartbeats again. The runtime
+    // limit, the terminal channel above, and sandbox cleanup bound this process.
   } finally {
     clearTimeout(timeout);
     if (heartbeatController === controller) heartbeatController = null;

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/absurd-runtime-worker.ts

@@ -45,6 +45,7 @@ import {
 } from '../app-runtime-api';
 import { RUNTIME_CAPACITY_POLICY } from '../runtime-capacity-policy';
 import { RUNTIME_RELIABILITY_POLICY } from '../runtime-reliability-policy';
+import { RUNTIME_CLAIM_HEARTBEAT_DIVISOR } from '../runtime-constants';
 import type { RuntimeTrafficPolicy } from '../runtime-traffic-policy';
 import { runtimeLimitExceededCause } from '../run-failure';
 import {
@@ -736,7 +737,7 @@ export class AbsurdExecutionOperationTimeoutError extends Error {
  * park/resume seam without a real engine. */
 export type AbsurdSuspensionContext = Pick<
   TaskContext,
-  'sleepFor' | 'sleepUntil' | 'awaitEvent' | 'heartbeat'
+  'sleepFor' | 'sleepUntil' | 'awaitEvent' | 'heartbeat' | 'step'
 >;
 
 /** Injected DB + app-runtime seams so the handler is testable against real SQL
@@ -1284,6 +1285,46 @@ function signalData(
   return null;
 }
 
+const LIVENESS_CONFIRMATION_SLICES_PER_CADENCE = 4;
+
+/**
+ * A stale heartbeat proves a lost runner only if the runner could have renewed
+ * it. During a scheduler-store stall no runner can, and the worker's own
+ * scheduling writes (`schedule_run` NOTIFYs) stall with it. So the worker
+ * counts only short sleep slices that woke on time, and decides after two
+ * heartbeat cadences of such observed availability. A late slice counts for
+ * nothing. Slice times and lateness are checkpointed, so replay is
+ * deterministic. Returns true when the runner stayed silent or the hard
+ * ceiling arrived, false as soon as it renewed or pushed its terminal.
+ */
+async function confirmDetachedRunnerSilence(input: {
+  ctx: AbsurdSuspensionContext;
+  stepPrefix: string;
+  cadenceMs: number;
+  ceilingDeadlineMs: number;
+  runnerResponded: () => Promise<boolean>;
+}): Promise<boolean> {
+  const sliceMs = Math.floor(
+    input.cadenceMs / LIVENESS_CONFIRMATION_SLICES_PER_CADENCE,
+  );
+  let observedMs = 0;
+  for (let slice = 1; observedMs < 2 * input.cadenceMs; slice += 1) {
+    const stepName = `${input.stepPrefix}:${slice}`;
+    const wakeAtMs = await input.ctx.step(`${stepName}:at`, async () =>
+      Math.min(input.ceilingDeadlineMs, Date.now() + sliceMs),
+    );
+    await input.ctx.sleepUntil(stepName, new Date(wakeAtMs));
+    if (await input.runnerResponded()) return false;
+    if (wakeAtMs >= input.ceilingDeadlineMs) return true;
+    const lateMs = await input.ctx.step(
+      `${stepName}:late`,
+      async () => Date.now() - wakeAtMs,
+    );
+    if (lateMs <= sliceMs) observedMs += sliceMs;
+  }
+  return true;
+}
+
 /**
  * Map a runner suspension onto an absurd durable primitive and return the
  * checkpoint with the resolved boundary output. THROWS `SuspendTask` when the
@@ -1382,9 +1423,30 @@ export async function parkAndResolveSuspension(input: {
         (Number.isFinite(renewedAtMs) ? renewedAtMs : suspension.startedAtMs) +
           heartbeatTimeoutMs,
       );
-      if (renewedDeadlineMs <= Date.now() || renewedDeadlineMs === deadlineMs) {
-        break;
+      if (renewedDeadlineMs > Date.now()) {
+        if (renewedDeadlineMs === deadlineMs) break;
+        continue;
       }
+      if (ceilingDeadlineMs <= Date.now()) break;
+      const readRunnerTerminal = input.readRunnerTerminal;
+      const readRunnerLiveness = input.readRunnerLiveness;
+      const silent = await confirmDetachedRunnerSilence({
+        ctx,
+        stepPrefix: `${suspension.boundaryId}:liveness-confirm:${Number.isFinite(renewedAtMs) ? renewedAtMs : 'none'}`,
+        cadenceMs: Math.floor(
+          heartbeatTimeoutMs / RUNTIME_CLAIM_HEARTBEAT_DIVISOR,
+        ),
+        ceilingDeadlineMs,
+        runnerResponded: async () => {
+          if (await readRunnerTerminal(suspension.runnerAttempt)) return true;
+          const current = await readRunnerLiveness(suspension.runnerAttempt);
+          const currentAtMs = current?.heartbeatAt
+            ? Date.parse(current.heartbeatAt)
+            : Number.NaN;
+          return Number.isFinite(currentAtMs) && !(currentAtMs <= renewedAtMs);
+        },
+      });
+      if (silent) break;
     }
     // Truth is the persisted terminal (read by the caller's wake path); the
     // absurd event carries no payload we trust.

package/dist/bundling-sources/shared_libs/plays/email-status.ts

@@ -53,6 +53,101 @@ export type EmailStatus = {
   };
 };
 
+const nullable = (type: string) => ({ type: [type, 'null'] });
+const oneOf = (values: readonly string[]) => ({ type: 'string', enum: values });
+
+/** `EmailStatus` as a JSON schema, for describing it where TypeScript types are not at hand. */
+export const EMAIL_STATUS_JSON_SCHEMA = {
+  type: 'object',
+  required: [
+    'verdict',
+    'status',
+    'verified',
+    'confidence',
+    'reasons',
+    'signals',
+    'provider',
+  ],
+  properties: {
+    verdict: oneOf([
+      'send',
+      'send_with_caution',
+      'verify_next',
+      'hold',
+      'drop',
+    ] satisfies EmailStatusVerdict[]),
+    status: oneOf([
+      'valid',
+      'invalid',
+      'catch_all',
+      'valid_catch_all',
+      'unknown',
+      'do_not_mail',
+      'spamtrap',
+      'abuse',
+      'disposable',
+    ] satisfies EmailStatusValue[]),
+    verified: { type: 'boolean' },
+    confidence: nullable('number'),
+    reasons: { type: 'array', items: { type: 'string' } },
+    signals: {
+      type: 'object',
+      required: [
+        'catch_all',
+        'deliverability',
+        'mx_class',
+        'mx_provider',
+        'mx_record',
+        'fraud_score',
+        'disposable',
+        'role_based',
+        'free_email',
+        'abuse',
+        'spamtrap',
+        'suspect',
+        'valid',
+      ] satisfies Array<keyof EmailStatus['signals']>,
+      properties: {
+        catch_all: nullable('boolean'),
+        deliverability: oneOf([
+          'high',
+          'medium',
+          'low',
+          'unknown',
+        ] satisfies EmailDeliverability[]),
+        mx_class: oneOf([
+          'consumer_mailbox',
+          'workspace_mailbox',
+          'security_gateway',
+          'on_prem',
+          'unknown',
+        ] satisfies EmailMxClass[]),
+        mx_provider: nullable('string'),
+        mx_record: nullable('string'),
+        fraud_score: nullable('number'),
+        disposable: nullable('boolean'),
+        role_based: nullable('boolean'),
+        free_email: nullable('boolean'),
+        abuse: nullable('boolean'),
+        spamtrap: nullable('boolean'),
+        suspect: nullable('boolean'),
+        valid: nullable('boolean'),
+      },
+    },
+    provider: {
+      type: 'object',
+      required: ['name', 'raw_status', 'raw_score'] satisfies Array<
+        keyof EmailStatus['provider']
+      >,
+      properties: {
+        name: { type: 'string' },
+        raw_status: { type: ['string', 'boolean', 'number', 'null'] },
+        raw_score: nullable('number'),
+      },
+    },
+  },
+} as const;
+
 export type EmailStatusMapEntry = {
   status: EmailStatusValue;
   verdict?: EmailStatusVerdict;

package/dist/bundling-sources/shared_libs/plays/extractor-targets.ts

@@ -18,6 +18,20 @@ export type JobChangeGetterValue = {
   new_title: string | null;
 };
 
+/** `JobChangeGetterValue` as a JSON schema. */
+export const JOB_CHANGE_JSON_SCHEMA = {
+  type: 'object',
+  required: ['status', 'date', 'new_company', 'new_title'] satisfies Array<
+    keyof JobChangeGetterValue
+  >,
+  properties: {
+    status: { type: 'string', enum: JOB_CHANGE_STATUS_VALUES },
+    date: { type: ['string', 'null'] },
+    new_company: { type: ['string', 'null'] },
+    new_title: { type: ['string', 'null'] },
+  },
+} as const;
+
 export const PHONE_STATUS_VALUES = ['valid', 'invalid', 'unknown'] as const;
 
 export type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];

package/dist/bundling-sources/shared_libs/plays/field-catalog.ts

@@ -0,0 +1,253 @@
+import type { DeeplineExtractorTarget } from './extractor-targets';
+
+/**
+ * The catalog of things a tool or play can take or return about a person or
+ * a company, named by what they are instead of by what a provider calls them.
+ *
+ * An id is a dotted path that always ends in a leaf:
+ *
+ *   person.email.value            any email for the person
+ *   person.email.work.value       their work email
+ *   person.email.work.validated   whether that work email was validated
+ *
+ * It reads `<entity>.<group>[.<kind>].<leaf>`. A group is one thing about the
+ * entity (an email). A leaf is one fact about that thing (its value, whether
+ * it was validated). A kind narrows which one is meant (work, personal). No
+ * id is both a field and a parent of fields, so `person.email` alone is never
+ * a field; the plain value is `person.email.value`.
+ *
+ * A kind is a narrowing, so a field with a kind also answers for the same
+ * field without it: a tool that returns `person.email.work.value` satisfies a
+ * request for `person.email.value`. A tool that cannot tell which kind it has
+ * declares the id without one.
+ *
+ * This is an addition. Existing short names (`email`, `name`) keep working;
+ * `EXTRACTOR_TARGET_FIELDS` records what each can mean.
+ */
+type Leaf = { type: string; description: string };
+
+type Group = {
+  description: string;
+  leaves: Record<string, Leaf>;
+  /** Narrowings of this group. Each has every leaf the group has. */
+  kinds?: Record<string, string>;
+};
+
+const value = (description: string): Leaf => ({ type: 'string', description });
+
+const SOURCE: Leaf = {
+  type: 'string',
+  description: 'The provider or step that found it.',
+};
+
+export const FIELD_CATALOG = {
+  person: {
+    name: {
+      description: "The person's name.",
+      leaves: {
+        value: value('Full name.'),
+        first: value('First (given) name.'),
+        last: value('Last (family) name.'),
+      },
+    },
+    email: {
+      description: 'An email address for the person.',
+      leaves: {
+        value: value('The address.'),
+        validated: {
+          type: 'boolean',
+          description: 'Whether the address passed validation.',
+        },
+        status: {
+          type: 'EmailStatus',
+          description: 'The validation verdict and its signals.',
+        },
+        source: SOURCE,
+      },
+      kinds: {
+        work: 'At their employer.',
+        personal: 'Their own, not tied to an employer.',
+      },
+    },
+    phone: {
+      description: 'A phone number for the person.',
+      leaves: {
+        value: value('The number.'),
+        validated: {
+          type: 'boolean',
+          description: 'Whether the number passed validation.',
+        },
+        status: {
+          type: '"valid" | "invalid" | "unknown"',
+          description: 'The validation verdict.',
+        },
+        line_type: value('Mobile, landline, VoIP and so on.'),
+        carrier: value('The carrier serving the number.'),
+        source: SOURCE,
+      },
+      kinds: {
+        mobile: 'Their mobile.',
+        work: 'A direct line at their employer.',
+      },
+    },
+    linkedin: {
+      description: "The person's LinkedIn profile.",
+      leaves: { url: value('The profile URL.') },
+    },
+    job: {
+      description: "The person's current role.",
+      leaves: {
+        title: value('Job title.'),
+        change: {
+          type: 'JobChange',
+          description: 'Whether they changed jobs, and to what.',
+        },
+        change_status: {
+          type: 'JobChangeStatus',
+          description: 'The job-change verdict alone.',
+        },
+      },
+    },
+    record: {
+      description: "A provider's own record of the person.",
+      leaves: { id: value("The provider's id for the person.") },
+    },
+  },
+  company: {
+    name: {
+      description: "The company's name.",
+      leaves: { value: value('The name.') },
+      kinds: { legal: 'As registered with a government.' },
+    },
+    domain: {
+      description: "The company's web domain.",
+      leaves: { value: value('The bare domain, such as example.com.') },
+    },
+    website: {
+      description: "The company's website.",
+      leaves: { url: value('The site URL.') },
+    },
+    linkedin: {
+      description: "The company's LinkedIn page.",
+      leaves: { url: value('The page URL.') },
+    },
+    phone: {
+      description: 'A phone number for the company.',
+      leaves: { value: value('The number.') },
+    },
+    industry: {
+      description: 'The industry the company is in.',
+      leaves: { value: value('The industry.') },
+    },
+    record: {
+      description: "A provider's own record of the company.",
+      leaves: { id: value("The provider's id for the company.") },
+    },
+  },
+} as const satisfies Record<string, Record<string, Group>>;
+
+export type FieldEntity = keyof typeof FIELD_CATALOG;
+
+export type CatalogField = Leaf & {
+  id: string;
+  entity: FieldEntity;
+  group: string;
+  kind?: string;
+  leaf: string;
+};
+
+/** Every field in the catalog, with and without each kind. */
+export function catalogFields(): CatalogField[] {
+  return Object.entries(FIELD_CATALOG).flatMap(([entity, groups]) =>
+    Object.entries<Group>(groups).flatMap(([group, definition]) =>
+      [undefined, ...Object.keys(definition.kinds ?? {})].flatMap((kind) =>
+        Object.entries(definition.leaves).map(([leaf, described]) => ({
+          ...described,
+          id: [entity, group, kind, leaf].filter(Boolean).join('.'),
+          entity: entity as FieldEntity,
+          group,
+          ...(kind ? { kind } : {}),
+          leaf,
+        })),
+      ),
+    ),
+  );
+}
+
+const FIELDS_BY_ID = new Map(catalogFields().map((field) => [field.id, field]));
+
+export function catalogField(id: string): CatalogField | undefined {
+  return FIELDS_BY_ID.get(id);
+}
+
+/** The same field without its kind, or null when it has none to drop. */
+export function generalField(id: string): string | null {
+  const field = FIELDS_BY_ID.get(id);
+  return field?.kind ? [field.entity, field.group, field.leaf].join('.') : null;
+}
+
+/** Whether a tool returning `offered` gives a caller what `wanted` asks for. */
+export function fieldSatisfies(offered: string, wanted: string): boolean {
+  return offered === wanted || generalField(offered) === wanted;
+}
+
+/**
+ * What each existing short output name can mean, as the general field: a tool
+ * may also declare any narrowing of one (`email` as `person.email.work.value`).
+ * One entry means the name means that everywhere unless a tool narrows it.
+ * Several mean it depends on the tool, which has to say. None means the name
+ * is used for things outside the catalog and stays a per-tool name.
+ */
+export const EXTRACTOR_TARGET_FIELDS: Record<
+  DeeplineExtractorTarget,
+  readonly string[]
+> = {
+  email: ['person.email.value'],
+  personal_email: ['person.email.personal.value'],
+  email_status: ['person.email.status'],
+  phone: ['person.phone.value', 'company.phone.value'],
+  phone_status: ['person.phone.status'],
+  first_name: ['person.name.first'],
+  last_name: ['person.name.last'],
+  full_name: ['person.name.value'],
+  // Also used for a list name, a channel title and a search suggestion.
+  name: ['person.name.value', 'company.name.value'],
+  linkedin: ['person.linkedin.url', 'company.linkedin.url'],
+  linkedin_url: ['person.linkedin.url'],
+  title: ['person.job.title'],
+  job_change: ['person.job.change'],
+  job_change_status: ['person.job.change_status'],
+  company: ['company.name.value'],
+  company_name: ['company.name.value'],
+  organization_name: ['company.name.value'],
+  company_domain: ['company.domain.value'],
+  domain: ['company.domain.value'],
+  company_website: ['company.website.url'],
+  // Also used for a podcast URL.
+  website: ['company.website.url'],
+  company_linkedin_url: ['company.linkedin.url'],
+  industry: ['company.industry.value'],
+  id: ['person.record.id', 'company.record.id'],
+  // Used for unrelated provider statuses; none is a catalog field.
+  status: [],
+};
+
+/**
+ * The catalog field a short name stands for on one tool: what the tool
+ * declares, or else the name's one meaning. Undefined when the name is
+ * ambiguous and the tool has not said, or when what it said is not something
+ * the name can mean.
+ */
+export function fieldOfName(
+  name: string,
+  declared?: string,
+): string | undefined {
+  const meanings: readonly string[] =
+    EXTRACTOR_TARGET_FIELDS[name as DeeplineExtractorTarget] ?? [];
+  if (declared === undefined) {
+    return meanings.length === 1 ? meanings[0] : undefined;
+  }
+  return meanings.some((meaning) => fieldSatisfies(declared, meaning))
+    ? declared
+    : undefined;
+}

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -55,6 +55,8 @@ export type ToolResultListMetadata = {
 
 export type ToolResultExtractorDescriptor = {
   paths: readonly string[];
+  /** The field catalog id this output is on this tool, when it declares one. */
+  means?: string;
   transforms?: readonly string[];
   enum?: readonly string[];
   overrides?: readonly ToolResultExtractorOverride[];