deepline 0.3.194 → 0.3.196

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

@@ -793,6 +793,13 @@ export type PlaysListOptions = {
    */
   grepMode?: 'all' | 'any' | 'phrase';
   categories?: string | string[];
+  /**
+   * Keep only plays carrying one of these tags — the job a play does, not the
+   * tools it calls. Deepline's closed vocabulary today: `smb`,
+   * `find-prospects`, `qualify`, `contact-info`, `signals`. Several tags widen
+   * the result rather than narrowing it, because a play carries exactly one.
+   */
+  tags?: string | string[];
   includeToolCategories?: boolean;
   includeArchived?: boolean;
   includeCostEstimates?: boolean;
@@ -5420,6 +5427,12 @@ export class DeeplineClient {
     if (options?.categories || options?.includeToolCategories) {
       params.set('include_tool_categories', '1');
     }
+    if (options?.tags) {
+      params.set(
+        'tags',
+        Array.isArray(options.tags) ? options.tags.join(',') : options.tags,
+      );
+    }
     if (options?.includeArchived) params.set('include_archived', '1');
     if (options?.includeCostEstimates) {
       params.set('include_cost_estimates', '1');

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.194',
+  version: '0.3.196',
   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

@@ -1378,6 +1378,14 @@ export interface PlayListItem {
   description?: string | null;
   pinned?: boolean;
   toolCategories?: string[];
+  /**
+   * The job the play does, from Deepline's closed prebuilt tag vocabulary
+   * (`smb`, `find-prospects`, `qualify`, `contact-info`, `signals`) — a
+   * different question from `toolCategories`, which reports the tools it
+   * calls. Empty for org-owned plays; absent from a server too old to report
+   * it.
+   */
+  tags?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   ownerSlug?: string;
@@ -1469,6 +1477,16 @@ export interface PlayDescription {
   description?: string | null;
   pinned?: boolean;
   toolCategories?: string[];
+  /**
+   * What job this play does, as a closed vocabulary — `smb`,
+   * `find-prospects`, `qualify`, `contact-info`, `signals`.
+   *
+   * Distinct from `toolCategories`, which is derived from the tool ids a play
+   * calls and so describes its MACHINERY. A play that calls an email tool is
+   * not thereby an email play; every SMB play calls one and none of them is.
+   * Empty for org-owned plays, which carry no registry tag.
+   */
+  tags?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   canEdit?: boolean;

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -885,6 +885,24 @@
     "failureAlert": "convex_action_wrapper",
     "domainReportRequired": true
   },
+  {
+    "id": "convex.cleanup-expired-api-key-claims",
+    "name": "Cleanup expired API key claims",
+    "scheduler": "convex_cron",
+    "cadence": "7 4 * * *",
+    "timezone": "UTC",
+    "source": "packages/convex/crons.ts",
+    "locator": "cleanup expired API key claims",
+    "owner": "auth",
+    "criticality": "maintenance",
+    "purpose": "Delete expired CLI claim tokens from apiKeyClaims, which had no reaper while a settings page view minted one durable claim row per unclaimed active key.",
+    "successDefinition": "The sweep advances its monotone createdAt watermark and deletes every expired claim it examines; zero expired claims is a valid no-op.",
+    "failureDefinition": "The sweep fails or stops advancing its watermark, leaving expired claim credentials retained indefinitely.",
+    "startGraceMs": 120000,
+    "runTimeoutMs": 1800000,
+    "failureAlert": "convex_action_wrapper",
+    "domainReportRequired": true
+  },
   {
     "id": "convex.cleanup-expired-analytics-ip2company-cache",
     "name": "Cleanup expired Analytics IP2Company cache entries",

package/dist/bundling-sources/shared_libs/observability/scheduled-work-manual.ts

@@ -11,6 +11,7 @@ export const MANUALLY_RUNNABLE_CONVEX_CRON_JOB_IDS = [
   'convex.fold-usage-rollups',
   'convex.record-neon-managed-project-usage',
   'convex.cleanup-expired-mcp-oauth-codes',
+  'convex.cleanup-expired-api-key-claims',
   'convex.cleanup-expired-analytics-ip2company-cache',
   'convex.cleanup-expired-domain-health-cache',
   'convex.salesforce-oauth-refresh-maintenance',

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

@@ -224,6 +224,21 @@ function isBatchableSinglePayload(
   );
 }
 
+// A single-contact payload carries request controls beside the contact.
+// Only contact fields belong in a bulk request's contacts[]; the controls are
+// copied once to the batch payload.
+function contactOf(payload: BetterContactSinglePayload): BetterContactContact {
+  const {
+    enrich_email_address: _enrichEmail,
+    enrich_phone_number: _enrichPhone,
+    wait_for_completion: _wait,
+    poll_interval_ms: _poll,
+    max_wait_ms: _maxWait,
+    ...contact
+  } = payload;
+  return contact;
+}
+
 function contactIdentity(contact: BetterContactContact): string {
   return stableStringify({
     first_name: contact.first_name,
@@ -642,8 +657,8 @@ const bettercontactSingleBatchStrategy: BatchOperationStrategy<
         ...copyControls(first),
         contacts: items.map((item) =>
           isBatchableSinglePayload(item.payload)
-            ? withItemKey(item.payload, item.itemKey)
-            : item.payload,
+            ? withItemKey(contactOf(item.payload), item.itemKey)
+            : contactOf(item.payload),
         ),
       },
       items,

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

@@ -72,7 +72,6 @@ import {
 } from '../runtime-api';
 import { PLAY_RUNTIME_ATTEMPT_EXECUTOR_TOKEN_PATH } from '../runtime-api-paths';
 import { vercelProtectionBypassHeaders } from '../vercel-protection';
-import { installPgRuntimePoolDriver } from '../runtime-pg-driver-pg';
 import {
   isManagedSandboxRuntimeBackend,
   normalizePlayRuntimeBackend,
@@ -302,7 +301,16 @@ class AttemptExecutorTokenCapacityError extends RuntimeSchedulerCapacityError {
     this.name = 'AttemptExecutorTokenCapacityError';
   }
 }
-installPgRuntimePoolDriver();
+
+// No `installPgRuntimePoolDriver()` here: the runtime Postgres driver belongs to
+// the process that owns this module's boot — `apps/absurd-runtime-worker` and
+// `apps/absurd-release-scaler` install it at their entrypoints. `apps/deepline-api`
+// imports the lane-count helpers below from a request path
+// (`src/lib/plays/runtime-lanes.ts`), and the Next.js dev server re-evaluates that
+// module graph on every recompile while `registerRuntimePoolFactory`'s registry
+// lives on `globalThis` under a `Symbol.for` key and survives. A module-scope
+// install therefore handed the registry a fresh factory object after each
+// recompile and tripped its one-driver-per-process assertion.
 
 /**
  * A slot supervises one remote Daytona sandbox; it is not a local compute

package/dist/bundling-sources/shared_libs/plays/docflow-binding-owner.ts

@@ -91,6 +91,21 @@ export function flattenSubsteps(
   return flat;
 }
 
+/**
+ * The names a substep's `field` answers to.
+ *
+ * A tool substep's field is a PATH, not a name: a step inside a `steps()`
+ * program is `steps.<step name>`, and a column's producer is
+ * `<column>.<step name>`. An `out:` contract names the step or column itself,
+ * so matching the whole path would never hit — `out:"contactout_personal"`
+ * against `steps.contactout_personal`. Both ends of the path are offered: the
+ * full path, and the last segment, which is the step/column the author named.
+ */
+function substepFieldSymbols(field: string): Set<string> {
+  const segments = field.split('.');
+  return new Set([field, segments[segments.length - 1]!]);
+}
+
 /** How a binding reached its substep — see the module header for the rules. */
 export type DocflowJoinVia = 'symbol' | 'extent';
 
@@ -115,6 +130,10 @@ export type DocflowLineExtent = { startLine: number; endLine: number };
 export function substepSourceExtent(
   substep: PlayStaticSubstep,
 ): DocflowLineExtent | null {
+  // Resolved through a call: the substep and everything under it live in the
+  // callee, so the only interval an annotation here can contain is the call.
+  const viaCall = callSiteExtent(substep);
+  if (viaCall) return viaCall;
   const ranges: PlayStaticSourceRange[] = [];
   const collect = (candidate: PlayStaticSubstep) => {
     if (candidate.sourceRange) ranges.push(candidate.sourceRange);
@@ -194,30 +213,73 @@ export type DocflowExtentResolver = (
 export function substepOwnSourceExtent(
   substep: PlayStaticSubstep,
 ): DocflowLineExtent | null {
+  const viaCall = callSiteExtent(substep);
+  if (viaCall) return viaCall;
   const range = substep.sourceRange;
   return range ? { startLine: range.startLine, endLine: range.endLine } : null;
 }
 
+/**
+ * The extent of the call a substep was reached through, when the extractor
+ * followed TypeScript symbol resolution into another function to find it.
+ *
+ * This is what lets a box annotated on `const x = await helper(ctx, …)` own the
+ * provider calls inside `helper` — including when `helper` is imported from
+ * another module, where the callee's own range is not even comparable to a line
+ * number in this file.
+ */
+function callSiteExtent(
+  substep: PlayStaticSubstep,
+): DocflowLineExtent | null {
+  const range = substep.callSiteRange;
+  return range ? { startLine: range.startLine, endLine: range.endLine } : null;
+}
+
+/**
+ * The extent a binding's line may be compared against.
+ *
+ * An annotation written in the ENTRY file keeps the existing behavior exactly:
+ * whatever the resolver prefers, no path check. An annotation written in an
+ * imported module is only comparable to a range from that same module — two
+ * files both have a line 42 — so it picks the substep's own range or its call
+ * site, whichever was recorded in the annotation's file, and matches nothing
+ * when neither was.
+ */
+function extentForBinding(
+  substep: PlayStaticSubstep,
+  binding: PlayDocflowBinding,
+  extentOf: DocflowExtentResolver,
+): DocflowLineExtent | null {
+  if (!binding.sourcePath) return extentOf(substep);
+  for (const range of [substep.sourceRange, substep.callSiteRange]) {
+    if (range?.sourcePath !== binding.sourcePath) continue;
+    return { startLine: range.startLine, endLine: range.endLine };
+  }
+  return null;
+}
+
 function extentContainsLine(
   substep: PlayStaticSubstep,
-  line: number,
+  binding: PlayDocflowBinding,
   extentOf: DocflowExtentResolver,
 ): DocflowLineExtent | null {
-  const extent = extentOf(substep);
+  const extent = extentForBinding(substep, binding, extentOf);
   if (!extent) return null;
-  return line >= extent.startLine && line <= extent.endLine ? extent : null;
+  return binding.line >= extent.startLine && binding.line <= extent.endLine
+    ? extent
+    : null;
 }
 
 /** Smallest containing extent wins, so a nested construct beats its parent. */
 function smallestContaining<TSubstep extends PlayStaticSubstep>(
   candidates: readonly TSubstep[],
-  line: number,
+  binding: PlayDocflowBinding,
   extentOf: DocflowExtentResolver = substepSourceExtent,
 ): TSubstep | null {
   let best: TSubstep | null = null;
   let bestSpan = Number.POSITIVE_INFINITY;
   for (const candidate of candidates) {
-    const extent = extentContainsLine(candidate, line, extentOf);
+    const extent = extentContainsLine(candidate, binding, extentOf);
     if (!extent) continue;
     const span = extent.endLine - extent.startLine;
     if (span < bestSpan) {
@@ -269,12 +331,12 @@ function joinBySymbolThenExtent<TSubstep extends PlayStaticSubstep>(
       // Two constructs compute the same column name. The one whose body the
       // annotation actually sits in decides; otherwise this is drift, and a
       // guess would attribute a member's rows to the wrong table.
-      const narrowed = smallestContaining(matches, binding.line, extentOf);
+      const narrowed = smallestContaining(matches, binding, extentOf);
       if (narrowed) return { substep: narrowed, via: 'symbol' };
       return { substep: null, reason: 'ambiguous' };
     }
   }
-  const positional = smallestContaining(candidates, binding.line, extentOf);
+  const positional = smallestContaining(candidates, binding, extentOf);
   if (positional) return { substep: positional, via: 'extent' };
   return { substep: null, reason: 'no-owner' };
 }
@@ -326,13 +388,53 @@ export function resolveDocflowBoundTool(
   const tools = substeps.filter(
     (substep): substep is DocflowToolSubstep => substep.type === 'tool',
   );
-  return joinBySymbolThenExtent(
-    binding,
-    tools,
-    (substep) => new Set([substep.field]),
+  return joinBySymbolThenExtent(binding, tools, (substep) =>
+    substepFieldSymbols(substep.field),
   );
 }
 
+/**
+ * EVERY tool a binding names, not just the one it unambiguously resolves to.
+ *
+ * {@link resolveDocflowBoundTool} answers "which single provider is this box",
+ * and correctly declines when a step calls two — a finder plus a validator, the
+ * shape every waterfall leg has. That decline is right for a headline tool and
+ * wrong for the Config surface, which exists to list a step's provider calls
+ * and their params. So this returns the whole set, in source order.
+ *
+ * Symbol match only: a step's tools are named by its `out:` contract. Extent is
+ * deliberately not a fallback here, because "every tool whose lines happen to
+ * sit inside this construct" would sweep up a sibling leg's calls.
+ */
+export function docflowBoundToolSubsteps(
+  binding: PlayDocflowBinding,
+  substeps: readonly PlayStaticSubstep[],
+): DocflowToolSubstep[] {
+  const roots = docflowOutputRoots(binding);
+  if (roots.length === 0) return [];
+  const matched: DocflowToolSubstep[] = [];
+  const seen = new Set<string>();
+  // Callers hand over whatever shape they hold — the config model passes the
+  // top-level stages, whose tools sit several levels down inside step suites
+  // and control flow. Flatten here so the answer never depends on that.
+  for (const substep of flattenSubsteps(substeps)) {
+    if (substep.type !== 'tool') continue;
+    const symbols = substepFieldSymbols(substep.field);
+    if (!roots.some((root) => symbols.has(root))) continue;
+    if (binding.sourcePath) {
+      const paths = [substep.sourceRange, substep.callSiteRange].map(
+        (range) => range?.sourcePath,
+      );
+      if (!paths.includes(binding.sourcePath)) continue;
+    }
+    const identity = `${substep.toolId}::${substep.paramsSource ?? ''}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    matched.push(substep);
+  }
+  return matched;
+}
+
 /**
  * The `ctx.runPlay` or `ctx.runPlayAsync` call a `type:"play"` docflow node
  * names. Same join as every other binding — symbol first, extent as the fallback
@@ -386,6 +488,13 @@ function legNameFromField(suiteField: string, legField: string): string {
  * field, and carrying only decidable facts about the text — never a claim about
  * whether this run reached it.
  */
+/** One provider call inside a leg, with the source of its input. */
+export type DocflowLegCall = {
+  toolId: string;
+  /** The authored expression passed as `input`, verbatim. Absent if unparsed. */
+  paramsSource?: string;
+};
+
 export type DocflowStepSuiteLeg = {
   /** The leg's durable step name — the string the author passed `.step(…)`. */
   name: string;
@@ -395,6 +504,14 @@ export type DocflowStepSuiteLeg = {
   toolId: string | null;
   /** Every provider call the leg makes, in order. */
   toolIds: string[];
+  /**
+   * The same calls, each with the source text of the input it is given.
+   *
+   * `toolIds` answers "which provider"; a reader looking at one attempt of a
+   * nine-attempt cascade also needs "with what" — the pane used to name the
+   * provider twice and never once say what it was called with.
+   */
+  calls: DocflowLegCall[];
   /** The leg is `runIf`-guarded, so whether it runs depends on earlier legs. */
   conditional: boolean;
   /** Every substep of the leg is statically off (`runIf: () => false`). */
@@ -415,12 +532,18 @@ export function stepSuiteLegs(
   for (const child of suite.steps ?? []) {
     const field = (child as { field?: string }).field ?? '';
     if (!field) continue;
-    const toolIds = flattenSubsteps([child])
-      .filter((step): step is DocflowToolSubstep => step.type === 'tool')
-      .map((step) => step.toolId);
+    const toolSteps = flattenSubsteps([child]).filter(
+      (step): step is DocflowToolSubstep => step.type === 'tool',
+    );
+    const toolIds = toolSteps.map((step) => step.toolId);
+    const calls: DocflowLegCall[] = toolSteps.map((step) => ({
+      toolId: step.toolId,
+      ...(step.paramsSource ? { paramsSource: step.paramsSource } : {}),
+    }));
     const existing = byField.get(field);
     if (existing) {
       existing.toolIds.push(...toolIds);
+      existing.calls.push(...calls);
       existing.toolId ??= toolIds[0] ?? null;
       existing.conditional ||= child.conditional === true;
       existing.disabled &&= child.disabled === true;
@@ -432,6 +555,7 @@ export function stepSuiteLegs(
       field,
       toolId: toolIds[0] ?? null,
       toolIds: [...toolIds],
+      calls: [...calls],
       conditional: child.conditional === true,
       disabled: child.disabled === true,
       nested: child.type === 'step_suite',

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -102,6 +102,16 @@ export type PlayDocflowSubgraph = {
 export type PlayDocflowBinding = {
   nodeId: string;
   line: number;
+  /**
+   * The file this annotation was written in, when it did not come from the play
+   * entry file. A play whose step program lives in a `-core` module has no
+   * statement in its `.play.ts` to annotate, so its boxes could only ever be
+   * sketches; annotations are read from the entry's import closure to fix that.
+   *
+   * `line` is only meaningful together with this: two files both have a line
+   * 42, so any positional comparison must agree on the path first.
+   */
+  sourcePath?: string;
   label?: string;
   kind?: PlayDocflowNodeKind;
   /** Symbolic values read by this business node. Never an arbitrary JS expression. */
@@ -153,6 +163,12 @@ export type ParsePlayDocflowOptions = {
    * both `scalar` and `default`.
    */
   exportName?: string | null;
+  /**
+   * Source of every module the entry imports, keyed by path. Annotations found
+   * here bind to the entry's diagrams exactly like the entry's own — routing is
+   * by node id, which never depended on which file the annotation sat in.
+   */
+  moduleSources?: ReadonlyMap<string, string> | null;
 };
 
 /** One `@mermaid` block, already bound to the export it describes. */
@@ -233,6 +249,8 @@ export function docflowLabelCountFragment(label: string): string | null {
 
 const FLOW_START = /^\s*(?:flowchart|graph)\s+(LR|RL|TB|TD|BT)\s*$/i;
 const MERMAID_NODE = /^\s*\/\/\s*@mermaid-node\s+([A-Za-z][\w-]*)(?:\s+(.*))?$/;
+/** Whole-file pre-filter for {@link MERMAID_NODE}; skips splitting clean files. */
+const MERMAID_NODE_HINT = /@mermaid-node/;
 const ATTRIBUTE = /([A-Za-z][\w-]*)\s*:\s*"([^"\n]*)"/y;
 const MERMAID_NODE_ATTRIBUTES = ['label', 'type', 'in', 'out', 'arm'] as const;
 const MERMAID_NODE_ID = /^[A-Za-z][\w-]*/;
@@ -929,6 +947,7 @@ function materializeDocflow(block: ParsedDocflowBlock): PlayDocflow {
  */
 export function parsePlayDocflowFile(
   sourceCode: string,
+  moduleSources?: ReadonlyMap<string, string> | null,
 ): PlayDocflowFileParseResult {
   const errors: string[] = [];
   const rawBlocks: Array<{
@@ -948,7 +967,19 @@ export function parsePlayDocflowFile(
   // the author already has one actionable error about them, and telling them to
   // "bind it" on the next line is telling them to do what they just did.
   const rejectedNodeIds = new Set<string>();
-  const bindings = parseDocflowBindings(sourceCode, errors, rejectedNodeIds);
+  // The entry first, then the modules it imports. Only files that actually
+  // contain an annotation are split into lines: a play's closure is mostly
+  // helpers and types, and this runs on every publish.
+  const annotationSources: DocflowAnnotationSource[] = [{ sourceCode }];
+  for (const [sourcePath, moduleCode] of moduleSources ?? []) {
+    if (!MERMAID_NODE_HINT.test(moduleCode)) continue;
+    annotationSources.push({ sourceCode: moduleCode, sourcePath });
+  }
+  const bindings = parseDocflowBindings(
+    annotationSources,
+    errors,
+    rejectedNodeIds,
+  );
 
   const parsedBlocks: ParsedDocflowBlock[] = [];
   for (const raw of rawBlocks) {
@@ -1326,7 +1357,7 @@ export function parsePlayDocflow(
   sourceCode: string,
   options: ParsePlayDocflowOptions = {},
 ): PlayDocflowParseResult {
-  const parsed = parsePlayDocflowFile(sourceCode);
+  const parsed = parsePlayDocflowFile(sourceCode, options.moduleSources);
   const requested = options.exportName?.trim() || PLAY_DEFAULT_EXPORT;
   const selected =
     parsed.blocks.find((block) => block.exportName === requested) ??
@@ -1354,10 +1385,32 @@ export function parsePlayDocflow(
  * to themselves afterwards; the annotations themselves are file-scoped text.
  */
 function parseDocflowBindings(
-  sourceCode: string,
+  sources: readonly DocflowAnnotationSource[],
+  errors: string[],
+  rejectedNodeIds: Set<string>,
+): PlayDocflowBinding[] {
+  const bindings: PlayDocflowBinding[] = [];
+  for (const source of sources) {
+    bindings.push(
+      ...parseDocflowBindingsInSource(source, errors, rejectedNodeIds),
+    );
+  }
+  return bindings;
+}
+
+/** One file that may carry `// @mermaid-node` annotations. */
+type DocflowAnnotationSource = {
+  sourceCode: string;
+  /** Omitted for the entry file, whose paths readers already know. */
+  sourcePath?: string;
+};
+
+function parseDocflowBindingsInSource(
+  source: DocflowAnnotationSource,
   errors: string[],
   rejectedNodeIds: Set<string>,
 ): PlayDocflowBinding[] {
+  const { sourceCode, sourcePath } = source;
   const lines = sourceCode.split(/\r?\n/);
   const bindings: PlayDocflowBinding[] = [];
 
@@ -1440,6 +1493,7 @@ function parseDocflowBindings(
     bindings.push({
       nodeId: id,
       line: nextLine + 1,
+      ...(sourcePath ? { sourcePath } : {}),
       ...(attributes.label ? { label: attributes.label } : {}),
       ...(kind ? { kind } : {}),
       // Spread, never `arm: arm ?? undefined` — see `PlayDocflowEdge.arm`. An

package/dist/bundling-sources/shared_libs/plays/share/static-pipeline-summary.ts

@@ -438,6 +438,9 @@ export function buildStaticPipelineSummary(
 // param sources never need to cross the public boundary.
 const SUBSTEP_STRIP_KEYS = new Set([
   'sourceRange',
+  // Same reason as `sourceRange`, and the same shape: it carries the absolute
+  // path of the file the call was made from, which is an author's machine.
+  'callSiteRange',
   'sourcePath',
   'callPath',
   'callDepth',

package/dist/bundling-sources/shared_libs/plays/static-pipeline.ts

@@ -757,6 +757,9 @@ function storageSafeNodeValue(
   if (asStaticRecord(value.sourceRange)) {
     out.sourceRange = { ...(value.sourceRange as Record<string, unknown>) };
   }
+  if (asStaticRecord(value.callSiteRange)) {
+    out.callSiteRange = { ...(value.callSiteRange as Record<string, unknown>) };
+  }
   if (asStaticRecord(value.sheetContract)) {
     out.sheetContract = cloneStorageSafeSheetContract(
       value.sheetContract as PlaySheetContract,
@@ -1224,6 +1227,24 @@ export interface PlayStaticSourceRange {
 type PlayStaticSubstepMetadata = {
   conditional?: boolean;
   disabled?: boolean;
+  /**
+   * Where this substep was REACHED FROM, when the extractor resolved it by
+   * following a call into another function — the range of the call expression
+   * itself, in the file that made the call.
+   *
+   * The extractor hops through `resolveLocalCallable`, which is TypeScript
+   * symbol resolution (`getSymbol()` / `getAliasedSymbol()`), so the callee may
+   * live anywhere in the import closure. Its `sourceRange` then points at the
+   * helper's body, which no annotation in the CALLING file can ever contain.
+   * That is why a binding on `const identity = await resolveCompanyIdentity(…)`
+   * could not reach the `ctx.tools.execute` inside it.
+   *
+   * Recorded as the OUTERMOST hop: unwinding stamps each level, so a tool three
+   * helpers deep ends up carrying the call site in the annotated function
+   * rather than an intermediate one. Absent whenever the substep was found
+   * directly in the function being analyzed.
+   */
+  callSiteRange?: PlayStaticSourceRange;
 };
 
 /**