deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/play-runtime/runtime-authority.ts

@@ -0,0 +1,201 @@
+import { mintWorkflowExecutorToken } from './/workflow-executor-auth';
+import {
+  DEFAULT_RUNTIME_EXECUTION_CAPABILITIES,
+  normalizeRuntimeExecutionCapabilities,
+  type RuntimeAuthorityDescriptor,
+  type RuntimeExecutionCapability,
+} from './/execution-capabilities';
+import type { FixtureBehavior } from './/fixture-behavior';
+import type { PlaySchedulerSubmitInput } from './/scheduler-backend';
+import type { DirectCompletedTerminalContract } from './/scheduler-backends/terminal-contract';
+
+export type RuntimeAuthority = {
+  executorToken: string;
+  descriptor: RuntimeAuthorityDescriptor;
+};
+
+/**
+ * Derive a child Run's durable authority from its admitted parent. The child
+ * owns its authored secret names and play identity; organization, actor,
+ * billing, scheduler placement, and capability policy remain parent-owned
+ * durable facts. This deliberately does not intersect secret names: a child
+ * Play resolves its own scoped declaration, where an equal name can identify
+ * a different Play-specific secret.
+ */
+export function deriveAsyncChildRuntimeAuthority(input: {
+  parent: RuntimeAuthorityDescriptor;
+  workflowId: string;
+  runId: string;
+  playName: string;
+  billingRunId: string;
+  allowedSecrets: readonly string[];
+}): RuntimeAuthorityDescriptor {
+  return {
+    orgId: input.parent.orgId,
+    workflowId: input.workflowId,
+    runId: input.runId,
+    // The scheduler-owned parent launch resolves the billing owner to the
+    // root before child admission. Keep the descriptor's token claim aligned
+    // with that durable run-state fact even for a legacy intermediate parent
+    // that predates `billingRunId` on its authority descriptor.
+    billingRunId: input.billingRunId,
+    playName: input.playName,
+    allowedSecrets: [...new Set(input.allowedSecrets)],
+    maxCreditsPerRun: input.parent.maxCreditsPerRun ?? null,
+    integrationMode: input.parent.integrationMode ?? null,
+    fixtureBehavior: input.parent.fixtureBehavior ?? null,
+    synthetic: input.parent.synthetic === true,
+    actorUserId: input.parent.actorUserId ?? null,
+    actorEmail: input.parent.actorEmail ?? null,
+    schedulerSchema: input.parent.schedulerSchema ?? null,
+    docflowEnabled: input.parent.docflowEnabled === true,
+    asyncChildAdmissionAttemptRequired:
+      input.parent.asyncChildAdmissionAttemptRequired === true,
+    capabilities: normalizeRuntimeExecutionCapabilities(
+      input.parent.capabilities,
+    ),
+  };
+}
+
+export async function mintPlayRunRuntimeAuthorityDescriptor(input: {
+  descriptor: RuntimeAuthorityDescriptor;
+  runtimeOrigin?: string | null;
+}): Promise<RuntimeAuthority> {
+  return {
+    descriptor: input.descriptor,
+    executorToken: await mintWorkflowExecutorToken({
+      ...runtimeAuthorityMintInput(input.descriptor),
+      runtimeOrigin: input.runtimeOrigin,
+    }),
+  };
+}
+
+export async function mintPlayRunRuntimeAuthority(input: {
+  orgId: string;
+  workflowId: string;
+  runId: string;
+  billingRunId?: string | null;
+  playName: string;
+  allowedSecrets?: readonly string[] | null;
+  maxCreditsPerRun?: number | null;
+  integrationMode?: 'live' | 'eval_stub' | 'fixture' | null;
+  fixtureBehavior?: FixtureBehavior | null;
+  synthetic?: boolean | null;
+  actorUserId?: string | null;
+  actorEmail?: string | null;
+  schedulerSchema?: string | null;
+  /** Docflow rollout answer for the launching actor, resolved by the caller. */
+  docflowEnabled?: boolean | null;
+  runtimeOrigin?: string | null;
+}): Promise<RuntimeAuthority> {
+  const descriptor: RuntimeAuthorityDescriptor = {
+    orgId: input.orgId,
+    workflowId: input.workflowId,
+    runId: input.runId,
+    billingRunId: input.billingRunId ?? null,
+    playName: input.playName,
+    allowedSecrets: [...new Set(input.allowedSecrets ?? [])],
+    maxCreditsPerRun: input.maxCreditsPerRun ?? null,
+    integrationMode: input.integrationMode ?? null,
+    fixtureBehavior: input.fixtureBehavior ?? null,
+    synthetic: input.synthetic === true,
+    actorUserId: input.actorUserId ?? null,
+    actorEmail: input.actorEmail ?? null,
+    schedulerSchema: input.schedulerSchema ?? null,
+    docflowEnabled: input.docflowEnabled === true,
+    capabilities: normalizeRuntimeExecutionCapabilities(
+      DEFAULT_RUNTIME_EXECUTION_CAPABILITIES,
+    ),
+  };
+  return await mintPlayRunRuntimeAuthorityDescriptor({
+    descriptor,
+    runtimeOrigin: input.runtimeOrigin,
+  });
+}
+
+export function runtimeAuthorityMintInput(
+  descriptor: RuntimeAuthorityDescriptor,
+  input: {
+    runAttempt?: number | null;
+    runLeaseToken?: string | null;
+    terminalContract?: DirectCompletedTerminalContract | null;
+    capabilities?: readonly RuntimeExecutionCapability[];
+    runtimeOrigin?: string | null;
+  } = {},
+) {
+  return {
+    orgId: descriptor.orgId,
+    workflowId: descriptor.workflowId,
+    runId: descriptor.runId,
+    billingRunId: descriptor.billingRunId,
+    playName: descriptor.playName,
+    allowedSecrets: descriptor.allowedSecrets,
+    maxCreditsPerRun: descriptor.maxCreditsPerRun,
+    integrationMode: descriptor.integrationMode,
+    fixtureBehavior: descriptor.fixtureBehavior,
+    synthetic: descriptor.synthetic,
+    actorUserId: descriptor.actorUserId,
+    actorEmail: descriptor.actorEmail,
+    schedulerSchema: descriptor.schedulerSchema,
+    runAttempt: input.runAttempt,
+    runLeaseToken: input.runLeaseToken,
+    terminalContract: input.terminalContract,
+    capabilities: input.capabilities ?? descriptor.capabilities,
+    runtimeOrigin: input.runtimeOrigin,
+  };
+}
+
+export async function mintPlayRunAttemptRuntimeToken(input: {
+  descriptor: RuntimeAuthorityDescriptor;
+  runAttempt?: number | null;
+  runLeaseToken?: string | null;
+  terminalContract?: DirectCompletedTerminalContract | null;
+  capabilities?: readonly RuntimeExecutionCapability[];
+  runtimeOrigin?: string | null;
+}): Promise<string> {
+  return await mintWorkflowExecutorToken(
+    runtimeAuthorityMintInput(input.descriptor, input),
+  );
+}
+
+/**
+ * Reconstruct the smallest authority needed to settle compute billing for a
+ * terminal launch row written before runtimeAuthority became durable state.
+ *
+ * This is deliberately not a general legacy-token fallback. The caller may
+ * mint only billing.write, and every fact comes from the leased launch row
+ * selected by the scheduler rather than the worker's request body.
+ */
+export function requireComputeBillingDispatchRuntimeAuthority(
+  launch: Pick<
+    PlaySchedulerSubmitInput,
+    'orgId' | 'runId' | 'playName' | 'userId' | 'userEmail'
+  >,
+): RuntimeAuthorityDescriptor {
+  const orgId = launch.orgId?.trim();
+  const runId = launch.runId?.trim();
+  const playName = launch.playName?.trim();
+  if (!orgId || !runId || !playName) {
+    throw new Error(
+      'Legacy compute-billing launch is missing orgId, runId, or playName.',
+    );
+  }
+
+  return {
+    orgId,
+    // Scheduler envelopes use the workflow id as the durable run id.
+    workflowId: runId,
+    runId,
+    billingRunId: runId,
+    playName,
+    allowedSecrets: [],
+    maxCreditsPerRun: null,
+    integrationMode: null,
+    fixtureBehavior: null,
+    synthetic: false,
+    actorUserId: launch.userId?.trim() || null,
+    actorEmail: launch.userEmail?.trim() || null,
+    docflowEnabled: false,
+    capabilities: ['billing.write'],
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-capacity-policy.ts

@@ -26,6 +26,14 @@ export const RUNTIME_CAPACITY_POLICY = {
     claimOperationTimeoutMs: 20_000,
     requestTimeoutMs: 30_000,
   },
+  sandboxAcquisition: {
+    /**
+     * Starting a Daytona sandbox is a provider control-plane transition, not
+     * an Absurd execution slot. Serialize starts within each worker process;
+     * once started, all eight execution slots may run concurrently.
+     */
+    daytonaConcurrentStartsPerProcess: 1,
+  },
 } as const;
 
 export const ABSURD_GLOBAL_RUN_CONCURRENCY =
@@ -96,6 +104,18 @@ function nonNegativeNumber(value: number): number {
 }
 
 export function assertRuntimeCapacityPolicy(): void {
+  if (
+    !Number.isInteger(
+      RUNTIME_CAPACITY_POLICY.sandboxAcquisition
+        .daytonaConcurrentStartsPerProcess,
+    ) ||
+    RUNTIME_CAPACITY_POLICY.sandboxAcquisition
+      .daytonaConcurrentStartsPerProcess <= 0
+  ) {
+    throw new Error(
+      'Daytona sandbox-start concurrency must be a positive integer.',
+    );
+  }
   if (
     RUNTIME_CAPACITY_POLICY.receiptGateway.requestTimeoutMs <=
     RUNTIME_CAPACITY_POLICY.receiptGateway.admissionTimeoutMs

package/dist/bundling-sources/shared_libs/play-runtime/runtime-contract.ts

@@ -3,11 +3,17 @@
  * receipt presentations. New operations must not use this as a version gate.
  */
 export const LEGACY_RUNTIME_RECEIPT_WIRE_HEADER = 'x-deepline-runtime-contract';
+// Frozen: production lane main-9281ae259f still sends wire format 2. Delete
+// this and `resolveLegacyRuntimeReceiptWireFormat` after that lane retires.
 export const LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT = 3 as const;
 /**
  * Historical workers validate this readiness range before they claim work.
  * It is an output-only compatibility presentation; current callers use named
  * operation capabilities and do not treat it as a global admission contract.
+ *
+ * Frozen: a lane built before the global compatibility gate was removed calls
+ * /readyz at boot and throws when this range is absent. Delete after every such
+ * lane has retired.
  */
 export const LEGACY_RUNTIME_READINESS_MIN_SUPPORTED = 1 as const;
 export const LEGACY_RUNTIME_READINESS_CURRENT = 6 as const;

package/dist/bundling-sources/shared_libs/play-runtime/runtime-env.ts

@@ -53,3 +53,15 @@ export function getRuntimeEnvInfo() {
     node_env: process.env.NODE_ENV ?? null,
   };
 }
+
+/** Test seams must never be reachable from a Vercel production deployment. */
+export function isTestOnlyRuntime(): boolean {
+  if (process.env.VERCEL_ENV === 'production') return false;
+  return process.env.VERCEL_ENV === 'preview' || getRuntimeEnv() !== 'prod';
+}
+
+export function shouldEnableMarketingIntegrations(): boolean {
+  return getRuntimeEnv() === 'prod';
+}
+
+export { isBuildContext } from '../observability/build-context';

package/dist/bundling-sources/shared_libs/play-runtime/runtime-operation-contract.ts

@@ -0,0 +1,67 @@
+import {
+  deployed,
+  type DeployedOperationContract,
+} from '@deepline/deployed-contracts';
+import type { RuntimeExecutionCapability } from './execution-capabilities';
+
+/**
+ * One declarative owner for the runtime action → authority relationship. The
+ * route still owns authentication and execution; callers can add an action in
+ * one obvious place and CI will prevent removing/changing an existing one.
+ */
+export const RUNTIME_OPERATION_CAPABILITIES = {
+  create_signed_artifact_url: 'artifact.read',
+  resolve_play: 'artifact.read',
+  create_signed_staged_file_url: 'file.read',
+  get_runtime_step_receipt: 'receipt.read',
+  get_runtime_step_receipts: 'receipt.read',
+  acquire_runtime_receipt_execution_lock: 'receipt.write',
+  release_runtime_receipt_execution_lock: 'receipt.write',
+  claim_runtime_step_receipt: 'receipt.write',
+  claim_runtime_step_receipts: 'receipt.write',
+  mark_runtime_step_receipt_running: 'receipt.write',
+  mark_runtime_step_receipts_running: 'receipt.write',
+  mark_runtime_step_receipts_queued: 'receipt.write',
+  complete_runtime_step_receipt: 'receipt.write',
+  complete_runtime_step_receipts: 'receipt.write',
+  release_runtime_step_receipt: 'receipt.write',
+  fail_runtime_step_receipt: 'receipt.write',
+  fail_runtime_step_receipts: 'receipt.write',
+  heartbeat_runtime_step_receipts: 'receipt.write',
+  skip_runtime_step_receipt: 'receipt.write',
+  ensure_sheet: 'sheet.write',
+  apply_row_updates: 'sheet.write',
+  create_db_session: 'db.session',
+  repair_runtime_storage_grants: 'sheet.write',
+  append_run_events: 'run.progress',
+  save_results: 'run.progress',
+  start_run: 'run.progress',
+  record_first_claim_latency: 'run.progress',
+  project_run_created: 'run.progress',
+  launch_play_async: 'run.child',
+  compute_billing_upsert: 'billing.write',
+  compute_billing_record_item: 'billing.write',
+  compute_billing_finalize: 'billing.write',
+  rate_state_acquire: 'rate.acquire',
+  rate_state_release: 'rate.acquire',
+  rate_state_penalize: 'rate.acquire',
+  get_runtime_traffic_policy: 'rate.acquire',
+  governor_budget_charge: 'budget.charge',
+  resolve_secret: 'secret.resolve',
+} as const satisfies Readonly<Record<string, RuntimeExecutionCapability>>;
+
+export const RUNTIME_OPERATION_CONTRACT: DeployedOperationContract =
+  deployed.operation({
+    id: 'runtime-api-actions',
+    actions: RUNTIME_OPERATION_CAPABILITIES,
+  });
+
+export function runtimeOperationCapability(
+  action: string,
+): RuntimeExecutionCapability | null {
+  return (
+    RUNTIME_OPERATION_CAPABILITIES[
+      action as keyof typeof RUNTIME_OPERATION_CAPABILITIES
+    ] ?? null
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-release-environment.ts

@@ -0,0 +1,2 @@
+/** Runtime estate owning one attested Runtime Release Bundle. */
+export type RuntimeReleaseEnvironment = 'preview' | 'production';

package/dist/bundling-sources/shared_libs/play-runtime/runtime-sandbox-contract.ts

@@ -0,0 +1,68 @@
+import { deployed, readDeployedObject } from '@deepline/deployed-contracts';
+
+export type RuntimeSandboxProviderId = 'daytona' | 'modal';
+
+export type RuntimeSandboxRef = {
+  /** Internal normalized form; persisted writer markers are diagnostic only. */
+  schemaVersion: 1;
+  provider: RuntimeSandboxProviderId;
+  resourceId: string;
+  routingDomain: string | null;
+};
+
+/**
+ * This ref lives in a durable suspension. Its provider and resource identity
+ * fence cleanup; its writer marker never decides whether a known sandbox can
+ * be reconciled by a different deployment.
+ */
+export const RUNTIME_SANDBOX_REF_CONTRACT = deployed.object({
+  id: 'runtime-sandbox-ref',
+  unknown: 'preserve',
+  fields: {
+    provider: deployed.openEnum(),
+    resourceId: deployed.string(),
+    routingDomain: deployed.json(),
+    schemaVersion: deployed.optional(deployed.diagnostic.number(), {
+      whenAbsent: 'diagnostic unavailable',
+    }),
+  },
+});
+
+export function readPersistedRuntimeSandboxRef(input: {
+  raw: unknown;
+  expectedSandboxId: string;
+  expectedProvider?: unknown;
+}): RuntimeSandboxRef {
+  const invalid = () =>
+    new Error(
+      `Persisted Runtime Sandbox Ref is invalid or inconsistent for sandbox ${input.expectedSandboxId}.`,
+    );
+  let value: Record<string, unknown>;
+  try {
+    value = readDeployedObject(RUNTIME_SANDBOX_REF_CONTRACT, input.raw).value;
+  } catch {
+    throw invalid();
+  }
+  const provider = value.provider;
+  const resourceId =
+    typeof value.resourceId === 'string' ? value.resourceId.trim() : '';
+  const routingDomain = value.routingDomain;
+  if (
+    (provider !== 'daytona' && provider !== 'modal') ||
+    !resourceId ||
+    resourceId !== input.expectedSandboxId.trim() ||
+    (routingDomain !== null && typeof routingDomain !== 'string') ||
+    (typeof routingDomain === 'string' && !routingDomain.trim()) ||
+    (input.expectedProvider !== undefined &&
+      input.expectedProvider !== provider)
+  ) {
+    throw invalid();
+  }
+  return {
+    schemaVersion: 1,
+    provider,
+    resourceId,
+    routingDomain:
+      typeof routingDomain === 'string' ? routingDomain.trim() : null,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-scheduler-topology.ts

@@ -1,6 +1,6 @@
 /**
  * Runtime-scheduler topology predicate shared by the app-side lane helpers
- * (`src/lib/plays/scheduler-backends/absurd-shared.ts`) and the runner
+ * (`packages/play-runtime/scheduler-backends/absurd-shared.ts`) and the runner
  * backends (`runner-backends/backends/daytona-lifecycle.ts`).
  *
  * ONE distinction drives several guards: a run whose scheduler schema is the
@@ -8,10 +8,34 @@
  * production egress policy), while any other schema is an ISOLATED topology —
  * a per-PR preview fleet or a per-worktree dev fleet running synthetic
  * internal test plays. Keeping the predicate here (dependency-free) lets
- * shared_libs code use it without importing the app-side scheduler stack.
+ * package code uses it without importing the app-side scheduler stack.
  */
 export const PROD_DEFAULT_RUNTIME_SCHEDULER_SCHEMA = 'runtime_scheduler';
 
+/** A wire-safe Postgres schema name that identifies one runtime topology. */
+export const RUNTIME_SCHEDULER_SCHEMA_RE = /^[a-z_][a-z0-9_]{0,62}$/;
+
+export function normalizeRuntimeSchedulerSchema(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const schema = value.trim();
+  return RUNTIME_SCHEDULER_SCHEMA_RE.test(schema) ? schema : null;
+}
+
+/**
+ * The one release-id shape. A release id is minted by the release controller
+ * and doubles as the lane's queue suffix (`runs_<releaseId>`) and the
+ * `DEEPLINE_RUNTIME_DEPLOY_VERSION` on every Machine in the lane, so it must be
+ * a stable lowercase engine-safe slug: no uppercase, no underscore, no repeated
+ * or trailing hyphen, 6 to 64 characters.
+ *
+ * It lives here, dependency-free, because the Fly lane operator, the release
+ * controller, the internal registry route, and the admin routes must all agree
+ * on it — a second copy is how one surface silently starts accepting an id the
+ * queue cannot name.
+ */
+export const ABSURD_RELEASE_ID_RE =
+  /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){5,63}$/;
+
 /**
  * True when the scheduler schema names an isolated (preview CI / worktree)
  * topology. Null/empty/prod-default => false (production topology). Callers
@@ -24,3 +48,15 @@ export function isIsolatedRuntimeSchedulerSchema(
   const schema = schedulerSchema?.trim();
   return Boolean(schema) && schema !== PROD_DEFAULT_RUNTIME_SCHEDULER_SCHEMA;
 }
+
+/**
+ * PostgreSQL LISTEN only improves wake-up latency; durable polling owns
+ * correctness. Isolated schemas deliberately share a small direct-connection
+ * budget across preview workers, so they use that polling path and leave
+ * direct sessions to the production topology.
+ */
+export function shouldUseRuntimeSchedulerDirectNotify(
+  schedulerSchema: string | null | undefined,
+): boolean {
+  return !isIsolatedRuntimeSchedulerSchema(schedulerSchema);
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-telemetry.ts

@@ -0,0 +1,108 @@
+import { createTelemetry } from '../observability/telemetry';
+
+type PlayRuntimeTelemetryInput = {
+  phase: string;
+  status: string;
+  orgId?: string | null;
+  runId?: string | null;
+  playName?: string | null;
+  graphHash?: string | null;
+  triggerSource?: string | null;
+  ms?: number;
+  errorCode?: string;
+};
+
+const playRuntimeTelemetry = createTelemetry({
+  service: 'deepline-api',
+  component: 'play-runtime',
+});
+
+type PlayTelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+
+function stringField(
+  fields: Record<string, unknown>,
+  ...keys: readonly string[]
+): string | null {
+  for (const key of keys) {
+    const value = fields[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+export function emitPlayTelemetry(input: {
+  level: PlayTelemetryLevel;
+  event: string;
+  tag: string;
+  fields?: Record<string, unknown>;
+  error?: unknown;
+}): void {
+  const fields = input.fields ?? {};
+  const telemetry = playRuntimeTelemetry.child({
+    context: {
+      orgId: stringField(fields, 'orgId', 'org_id'),
+      orgName: stringField(fields, 'orgName', 'org_name'),
+      requestId: stringField(fields, 'requestId', 'request_id'),
+      runId: stringField(fields, 'runId', 'run_id'),
+      workflowId: stringField(fields, 'workflowId', 'workflow_id', 'runId'),
+      playName: stringField(fields, 'playName', 'play_name'),
+    },
+  });
+  const options = { tag: input.tag };
+  if (input.level === 'error') {
+    void telemetry.error(input.event, input.error, fields, options);
+  } else {
+    void telemetry[input.level](input.event, fields, options);
+  }
+}
+
+/**
+ * Emit the stable play.runtime.span event consumed by Axiom dashboards.
+ * Domain fields stay unchanged while the shared telemetry envelope supplies
+ * consistent service, context, severity, and schema metadata.
+ */
+export function emitPlayRuntimeSpan(input: PlayRuntimeTelemetryInput): void {
+  emitPlayTelemetry({
+    level: 'info',
+    event: 'play.runtime.span',
+    tag: '[play.runtime.span]',
+    fields: {
+      orgId: input.orgId,
+      runId: input.runId,
+      workflowId: input.runId,
+      playName: input.playName,
+      phase: input.phase,
+      status: input.status,
+      graphHash: input.graphHash,
+      triggerSource: input.triggerSource,
+      ms: input.ms,
+      errorCode: input.errorCode,
+    },
+  });
+}
+
+export function emitRecoveredSecretResolutionRetry(input: {
+  orgId: string;
+  runId?: string | null;
+  playName?: string | null;
+  requestId: string;
+  operationId: string;
+  attempt: number;
+  httpStatus: number;
+}): void {
+  emitPlayTelemetry({
+    level: 'warn',
+    event: 'play.runtime.secret_resolution_retry_recovered',
+    tag: '[play.runtime.secret_resolution_retry_recovered]',
+    fields: {
+      orgId: input.orgId,
+      runId: input.runId,
+      workflowId: input.runId,
+      playName: input.playName,
+      requestId: input.requestId,
+      operationId: input.operationId,
+      attempt: input.attempt,
+      httpStatus: input.httpStatus,
+    },
+  });
+}

package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runs/contract.ts

@@ -230,6 +230,8 @@ export type SandboxExecutionAdmission = {
         leaseId: string;
         /** Stable provider correlation for operation-first managed creates. */
         providerOperationToken?: string | null;
+        /** Resume the existing durable provider operation before any new create. */
+        resumeExistingProviderOperation?: boolean;
       }
     | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
   >;
@@ -293,6 +295,8 @@ export type SandboxExecutionLifecycle = {
         leaseId: string;
         /** Stable provider correlation for operation-first managed creates. */
         providerOperationToken?: string | null;
+        /** Resume the existing durable provider operation before any new create. */
+        resumeExistingProviderOperation?: boolean;
       }
     | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
   >;

package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runs/runner-backend-adapter.ts

@@ -180,6 +180,9 @@ function createRunnerCallbacks(input: {
       return {
         leaseId: outcome.leaseId,
         providerOperationToken: outcome.providerOperationToken ?? null,
+        ...(outcome.resumeExistingProviderOperation === true
+          ? { resumeExistingProviderOperation: true }
+          : {}),
       };
     },
     releaseSandboxCapacity: async (leaseId) => {

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -41,10 +41,43 @@ export type { PlayRunInputPayload };
 
 export type PlaySchedulerSubmitInput = {
   runId: string;
+  /** First-class async-child lineage. Absent for root launches. */
+  parentRunId?: string | null;
+  rootRunId?: string | null;
+  asyncLaunchKey?: string | null;
+  asyncInvocationKey?: string | null;
+  asyncRequestFingerprint?: string | null;
+  /**
+   * Ephemeral proof carried only into atomic async-child admission. It is never
+   * persisted on the child launch; the child receives its own authority.
+   */
+  asyncParentRunAttempt?: number | null;
+  asyncParentRunLeaseToken?: string | null;
+  asyncParentAttemptRequired?: boolean | null;
+  /** Full play ancestry for a scheduled child, including this play. */
+  asyncAncestryPlayIds?: string[] | null;
   playId: string;
   playName: string;
+  playReference?: string | null;
+  /**
+   * Immutable scheduler namespace for this admission. The durable
+   * `run.created` projector persists it onto the Play Run so replay/control
+   * paths stay on the original runtime lane instead of falling back to a host
+   * default.
+   */
+  schedulerSchema?: string | null;
+  definitionScope?: 'org' | 'system' | null;
+  revisionId?: string | null;
   workflowFamilyKey?: string | null;
   artifactStorageKey: string;
+  /**
+   * The runtime PostgreSQL admission path committed this launch before its
+   * Convex `run.created` projection exists. The worker must deliver that
+   * causal fact before it can claim an execution attempt.
+   *
+   * Omitted for legacy launches whose Play Run row was persisted synchronously.
+   */
+  requiresRunCreatedProjection?: boolean;
   /** Optional inline artifact for the Node scheduler. */
   runtimeArtifact?: unknown;
   artifactHash: string;
@@ -52,6 +85,9 @@ export type PlaySchedulerSubmitInput = {
   /** Immutable scheduler/worker/runner ABI snapshot (not a Git SHA). */
   runtimeProtocolVersion?: PlayRuntimeProtocolVersion | null;
   input: PlayRunInputPayload;
+  /** Bounded launch metadata used only by the asynchronous ledger projector. */
+  staticPipeline?: unknown;
+  inputSummary?: Record<string, unknown>;
   /** Convex metadata for the exact input saved before scheduler submission. */
   inputFileId?: string;
   inputBytes?: number;
@@ -127,7 +163,7 @@ export type PlaySchedulerSubmitInput = {
   userId?: string | null;
   source?: 'published' | 'ad_hoc' | 'draft';
   /** Invocation origin, distinct from the artifact source above. */
-  triggerSource?: 'api' | 'webhook' | 'cron' | 'sql_listener';
+  triggerSource?: 'api' | 'webhook' | 'cron' | 'sql_listener' | 'async_child';
   /** Null lets a durable trigger wait for capacity; a number bounds queue delay. */
   queueMaxDelaySeconds?: number | null;
   /**