deepline 0.3.87 → 0.3.89

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

@@ -28,21 +28,16 @@ export type PlayRuntimeFeature =
   | 'durable_sleep'
   | 'packaged_files';
 
-export const PLAY_PUBLIC_API_VERSION = 1;
 export const PLAY_ARTIFACT_VERSION = CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION;
-export const PLAY_MIN_RUNNER_VERSION = 1;
-export const PLAY_RUNTIME_FEATURES: PlayRuntimeFeature[] = [
-  'artifact_storage',
-  'checkpoint_resume',
-  'durable_sleep',
-  'packaged_files',
-];
 
 export type PlayContractCompatibilitySnapshot = {
-  apiVersion: number;
+  /** Historical marker. Nothing admits, gates, or branches on it. */
+  apiVersion?: number;
   artifactVersion: number;
-  minRunnerVersion: number;
-  runtimeFeatures: PlayRuntimeFeature[];
+  /** Historical marker. Every runner reads every artifact. */
+  minRunnerVersion?: number;
+  /** Historical marker. Capabilities are named per operation, not listed here. */
+  runtimeFeatures?: PlayRuntimeFeature[];
   runtimeBackend?: string | null;
   /** Every Play run uses the structured tool-error contract. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
@@ -142,10 +137,7 @@ export function buildPlayContractCompatibility(input?: {
   toolResponseReceiptRevision?: string;
 }): PlayContractCompatibilitySnapshot {
   return {
-    apiVersion: PLAY_PUBLIC_API_VERSION,
     artifactVersion: PLAY_ARTIFACT_VERSION,
-    minRunnerVersion: PLAY_MIN_RUNNER_VERSION,
-    runtimeFeatures: [...PLAY_RUNTIME_FEATURES],
     runtimeBackend: input?.runtimeBackend ?? null,
     toolErrorSchemaVersion:
       input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION,

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

@@ -13,6 +13,9 @@ import type {
   PlayAuthoringDefinedPlay,
   PlayAuthoringInputContract,
   PlayAuthoringReferenceLike,
+  AsyncPlayRunRef as PlayAuthoringAsyncPlayRunRef,
+  PlayAuthoringAsyncCallOptions,
+  PlayRunId as PlayAuthoringRunId,
   PlayAuthoringRuntimeContext,
   PlayAuthoringStepOptions,
   PlayAuthoringStepProgram,
@@ -125,7 +128,12 @@ export type DatasetBuilder<
   DeeplinePlayRuntimeContext
 >;
 
-export type PlayReferenceLike = PlayAuthoringReferenceLike;
+export type PlayReferenceLike<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> = PlayAuthoringReferenceLike<TInput>;
+export type AsyncPlayRunRef = PlayAuthoringAsyncPlayRunRef;
+export type PlayAsyncCallOptions = PlayAuthoringAsyncCallOptions;
+export type PlayRunId = PlayAuthoringRunId;
 
 export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
 
@@ -444,10 +452,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 /** @internal Contextually type unannotated monitor-event handlers as unknown. */
 export function definePlay<TOutput extends PlayReturnObject>(
   name: string,
-  fn: (
-    context: DeeplinePlayRuntimeContext,
-    input: unknown,
-  ) => Promise<TOutput>,
+  fn: (context: DeeplinePlayRuntimeContext, input: unknown) => Promise<TOutput>,
   bindings: PlayBindings<never> & {
     readonly sqlListeners: readonly SqlListenerDeclaration[];
   },
@@ -455,7 +460,7 @@ export function definePlay<TOutput extends PlayReturnObject>(
 /* eslint-disable @typescript-eslint/no-explicit-any -- This constraint must infer a concrete contravariant handler input. */
 export function definePlay<
   THandler extends (
-  context: DeeplinePlayRuntimeContext,
+    context: DeeplinePlayRuntimeContext,
     input: any,
   ) => Promise<PlayReturnObject>,
 >(

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

@@ -61,10 +61,12 @@ export type DocflowOwnerSubstep = Extract<
   { type: 'dataset' | 'csv' }
 >;
 export type DocflowToolSubstep = Extract<PlayStaticSubstep, { type: 'tool' }>;
-export type DocflowPlayCallSubstep = Extract<
+export type DocflowChildPlaySubstep = Extract<
   PlayStaticSubstep,
-  { type: 'play_call' }
+  { type: 'play_call' | 'play_launch' }
 >;
+/** @deprecated Use `DocflowChildPlaySubstep`; retained for compatibility. */
+export type DocflowPlayCallSubstep = DocflowChildPlaySubstep;
 export type DocflowStepSuiteSubstep = Extract<
   PlayStaticSubstep,
   { type: 'step_suite' }
@@ -332,19 +334,19 @@ export function resolveDocflowBoundTool(
 }
 
 /**
- * The `ctx.runPlay` call a `type:"play"` docflow node names. Same join as every
- * other binding — symbol first, extent as the fallback — over the FLATTENED
- * substep tree, because a child call inside a `.withColumn(...)` body is nested
- * under its dataset. A `play_call`'s `field` is the column or variable the child
- * result lands in, which is exactly what the node's `out:` names.
+ * 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
+ * — over the FLATTENED substep tree. Its `field` is the column, variable, or
+ * launch key the child run lands in, which is exactly what the node's `out:`
+ * names.
  */
-export function resolveDocflowBoundPlayCall(
+export function resolveDocflowBoundChildPlay(
   binding: PlayDocflowBinding,
   substeps: readonly PlayStaticSubstep[],
-): DocflowBindingJoin<DocflowPlayCallSubstep> {
+): DocflowBindingJoin<DocflowChildPlaySubstep> {
   const playCalls = flattenSubsteps(substeps).filter(
-    (substep): substep is DocflowPlayCallSubstep =>
-      substep.type === 'play_call',
+    (substep): substep is DocflowChildPlaySubstep =>
+      substep.type === 'play_call' || substep.type === 'play_launch',
   );
   return joinBySymbolThenExtent(
     binding,
@@ -353,6 +355,9 @@ export function resolveDocflowBoundPlayCall(
   );
 }
 
+/** @deprecated Use `resolveDocflowBoundChildPlay`; retained for compatibility. */
+export const resolveDocflowBoundPlayCall = resolveDocflowBoundChildPlay;
+
 // ── waterfalls: the step suite and its legs ─────────────────────────────────
 //
 // `steps().step('hunter_email', …).step('leadmagic_email', …).return(…)` compiles

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

@@ -136,7 +136,7 @@ async function resolvePipelineSubsteps(input: {
         return nested satisfies PlayStaticSubstep;
       }
 
-      if (annotated.type !== 'play_call') {
+      if (annotated.type !== 'play_call' && annotated.type !== 'play_launch') {
         return annotated;
       }
 

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

@@ -0,0 +1,115 @@
+/**
+ * Canonical slug helpers — the single home for URL-handle normalization and
+ * unguessable-suffix generation. Shared by Convex (relative `.//slug`)
+ * and the Next app (`.//slug`).
+ *
+ * Used by:
+ * - Organization slugs (the org's stable URL handle)
+ * - Share-page slugs (`/p/{shareSlug}`) and version paths
+ * - Play-name slug bases
+ *
+ * Intentionally NOT covered here (different concerns — kept separate so this
+ * stays a real seam, not DRY-for-its-own-sake):
+ * - URL → durable-scope slugs (parse host:port; playground backend / scripts)
+ * - DataForSEO codegen `kebabCase` (underscore-only transform)
+ */
+
+const SHARE_SLUG_NAME_MAX_LEN = 48;
+const SHARE_SLUG_SUFFIX_LEN = 8;
+const SUFFIX_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Normalize an arbitrary string into a URL-safe kebab slug: lowercase, NFKD-fold
+ * accents, collapse every run of non-`[a-z0-9]` into a single dash, trim edge
+ * dashes, and optionally cap length (re-trimming a trailing dash after the cut).
+ *
+ * Returns `''` for empty/garbage input — callers supply their own domain
+ * fallback (`'team'`, `'play'`, `'ci-bootstrap'`, …), since the right default is
+ * domain-specific.
+ */
+export function normalizeSlug(
+  value: string,
+  options?: { maxLength?: number },
+): string {
+  let slug = value
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const maxLength = options?.maxLength;
+  if (maxLength !== undefined && slug.length > maxLength) {
+    slug = slug.slice(0, maxLength).replace(/-+$/g, '');
+  }
+  return slug;
+}
+
+/**
+ * Deterministic unguessable suffix from injected bytes (pure + testable). Each
+ * byte maps into a 36-char lowercase-alphanumeric alphabet. `randomBytes` must
+ * be at least `length` long.
+ */
+export function buildSlugSuffix(
+  length: number,
+  randomBytes: Uint8Array,
+): string {
+  if (randomBytes.length < length) {
+    throw new Error(
+      `buildSlugSuffix requires at least ${length} random bytes.`,
+    );
+  }
+  let suffix = '';
+  for (let i = 0; i < length; i += 1) {
+    suffix += SUFFIX_ALPHABET[randomBytes[i] % SUFFIX_ALPHABET.length];
+  }
+  return suffix;
+}
+
+/** Crypto-backed unguessable suffix (Node / Convex / browser global `crypto`). */
+export function randomSlugSuffix(length: number): string {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return buildSlugSuffix(length, bytes);
+}
+
+/** Kebab-case the human play name into the readable share-slug stem. */
+export function playNameToSlugBase(name: string): string {
+  return normalizeSlug(name, { maxLength: SHARE_SLUG_NAME_MAX_LEN }) || 'play';
+}
+
+/**
+ * Build a full share slug from a name stem and a source of randomness. Pure +
+ * deterministic for tests; callers pass crypto-backed bytes.
+ */
+export function buildShareSlug(name: string, randomBytes: Uint8Array): string {
+  const suffix = buildSlugSuffix(SHARE_SLUG_SUFFIX_LEN, randomBytes);
+  return `${playNameToSlugBase(name)}-${suffix}`;
+}
+
+/** Generate a crypto-backed share slug. */
+export function generateShareSlug(name: string): string {
+  return `${playNameToSlugBase(name)}-${randomSlugSuffix(SHARE_SLUG_SUFFIX_LEN)}`;
+}
+
+/**
+ * Public path for a share page — namespaced by org slug + play name.
+ *
+ * This is the ONLY public URL shape. There is no top-level `/p/{slug}`: org
+ * slugs are globally unique (Better Auth) and play names are unique within an
+ * org (`by_orgId_name`), so `{org}/{play}` is globally unique on its own. The
+ * random `shareSlug` is kept only as an internal record id, never a URL.
+ */
+export function buildSharePublicPath(
+  orgSlug: string,
+  playName: string,
+): string {
+  return `/p/${encodeURIComponent(orgSlug)}/${encodeURIComponent(playName)}`;
+}
+
+/** Canonical, version-pinned path for a share page. */
+export function buildShareCanonicalPath(
+  orgSlug: string,
+  playName: string,
+  version: number,
+): string {
+  return `${buildSharePublicPath(orgSlug, playName)}/v/${version}`;
+}

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

@@ -212,7 +212,10 @@ export function ensureCompiledSheetContract(
     substeps: PlayStaticSubstep[],
   ): PlayStaticSubstep[] =>
     substeps.map((substep) => {
-      if (substep.type === 'play_call' && substep.pipeline) {
+      if (
+        (substep.type === 'play_call' || substep.type === 'play_launch') &&
+        substep.pipeline
+      ) {
         return {
           ...substep,
           pipeline: ensureCompiledSheetContract(substep.pipeline) ?? null,
@@ -409,7 +412,11 @@ function truncateStaticSubstepsForStorage(
       return truncateStaticSubstepShallowForStorage(base);
     }
 
-    if (base.type !== 'play_call' && 'pipeline' in substepWithoutSourceText) {
+    if (
+      base.type !== 'play_call' &&
+      base.type !== 'play_launch' &&
+      'pipeline' in substepWithoutSourceText
+    ) {
       const nestedPipeline = substepWithoutSourceText.pipeline;
       (base as { pipeline?: PlayStaticPipeline | null }).pipeline =
         nestedPipeline
@@ -489,7 +496,7 @@ function truncateStaticSubstepsForStorage(
       });
     }
 
-    if (base.type !== 'play_call') {
+    if (base.type !== 'play_call' && base.type !== 'play_launch') {
       if (Array.isArray((base as { steps?: unknown }).steps)) {
         return omitUndefinedProperties({
           ...base,
@@ -502,9 +509,9 @@ function truncateStaticSubstepsForStorage(
       return base;
     }
 
-    // A normalized authoring graph intentionally leaves a named play-call's
-    // child pipeline absent. That is a reference edge, not a failed or
-    // truncated resolution, so preserve it without inventing an error.
+    // A normalized authoring graph may leave a named Play reference's child
+    // pipeline absent. That is a reference edge, not a failed or truncated
+    // resolution, so preserve it without inventing an error.
     if (
       !base.pipeline &&
       !Object.prototype.hasOwnProperty.call(substep, 'pipeline') &&
@@ -617,11 +624,7 @@ export function createStaticPipelineReferenceProjection(
     preserveEmbeddedPlayIds?: ReadonlySet<string>;
   },
 ): PlayStaticPipeline | null | undefined {
-  const stored = truncateStaticPipelineForStorage(pipeline, {
-    maxEmbeddedPlayCallPipelineDepth: Number.POSITIVE_INFINITY,
-    maxStoredSubstepDepth: Number.POSITIVE_INFINITY,
-  });
-  if (!stored) return stored;
+  if (!pipeline) return pipeline;
 
   const projectSteps = (
     steps: PlayStaticSubstep[] | undefined,
@@ -653,6 +656,10 @@ export function createStaticPipelineReferenceProjection(
         }
         return projected;
       }
+      if (projected.type === 'play_launch' && projected.pipeline) {
+        projected.pipeline = projectPipeline(projected.pipeline);
+        return projected;
+      }
       if (
         (projected.type === 'dataset' ||
           projected.type === 'step_suite' ||
@@ -678,7 +685,13 @@ export function createStaticPipelineReferenceProjection(
     substeps: projectSteps(candidate.substeps),
   });
 
-  return projectPipeline(stored);
+  // Prune named child snapshots before the storage-safe deep copy. Resolved
+  // calls can share large child graphs; copying those once per call site only
+  // to discard them can exhaust the launch process before run admission.
+  return truncateStaticPipelineForStorage(projectPipeline(pipeline), {
+    maxEmbeddedPlayCallPipelineDepth: Number.POSITIVE_INFINITY,
+    maxStoredSubstepDepth: Number.POSITIVE_INFINITY,
+  });
 }
 
 function asStaticRecord(value: unknown): Record<string, unknown> | null {
@@ -1315,6 +1328,19 @@ export type PlayStaticSubstep = PlayStaticSubstepMetadata &
         callDepth?: number;
         callPath?: string[];
       }
+    | {
+        type: 'play_launch';
+        playId: string;
+        field: string;
+        inLoop?: boolean;
+        pipeline?: PlayStaticPipeline | null;
+        cycleDetected?: boolean;
+        resolutionError?: string;
+        description?: string;
+        sourceRange?: PlayStaticSourceRange;
+        callDepth?: number;
+        callPath?: string[];
+      }
     | {
         type: 'control_flow';
         kind: 'conditional' | 'loop';
@@ -1601,7 +1627,7 @@ function columnProducerFromSubstep(
           ? 'stepProgram'
           : substep.type === 'control_flow'
             ? 'controlFlow'
-            : substep.type === 'play_call'
+            : substep.type === 'play_call' || substep.type === 'play_launch'
               ? 'playCall'
               : 'transform';
   return {
@@ -1609,7 +1635,9 @@ function columnProducerFromSubstep(
     kind,
     field,
     ...(substep.type === 'tool' ? { toolId: substep.toolId } : {}),
-    ...(substep.type === 'play_call' ? { playId: substep.playId } : {}),
+    ...(substep.type === 'play_call' || substep.type === 'play_launch'
+      ? { playId: substep.playId }
+      : {}),
     ...(substep.conditional ? { conditional: true } : {}),
     ...(substep.disabled ? { disabled: true } : {}),
     ...(substep.sourceRange ? { sourceRange: substep.sourceRange } : {}),
@@ -1624,6 +1652,8 @@ function producerId(substep: PlayStaticSubstep, field: string): string {
     return `${field}:waterfall:${substep.id ?? substep.tool ?? 'unknown'}`;
   }
   if (substep.type === 'play_call') return `${field}:play:${substep.playId}`;
+  if (substep.type === 'play_launch')
+    return `${field}:play-launch:${substep.playId}`;
   if (substep.type === 'step_suite') return `${field}:steps`;
   if (substep.type === 'control_flow')
     return `${field}:control:${substep.kind}:${sourceRangeKey(substep.sourceRange)}`;