deepline 0.2.12 → 0.2.14

package/dist/bundling-sources/shared_libs/play-runtime/csv-rename.ts

@@ -1,10 +1,14 @@
-export type CsvRenameMap = Record<string, string | readonly string[]>;
+import type {
+  PlayAuthoringCsvOptions,
+  PlayAuthoringCsvRenameMap,
+} from '../plays/authoring-contract';
 
-export type CsvRenameOptions = {
-  columns?: CsvRenameMap;
-  rename?: CsvRenameMap;
-  required?: readonly string[];
-};
+export type CsvRenameMap = PlayAuthoringCsvRenameMap;
+
+export type CsvRenameOptions = Pick<
+  PlayAuthoringCsvOptions,
+  'columns' | 'rename' | 'required'
+>;
 
 const CSV_PROJECTED_FIELDS = Symbol.for('deepline.play.csv.projected_fields');
 const CSV_PROJECTED_FIELDS_KEY = '__deeplineCsvProjectedFields';

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -3,6 +3,18 @@ import type { PlayBundleArtifact } from '../plays/artifact-types';
 import type { PlayRunContractSnapshot } from '../plays/contracts';
 import type { PlayStructuredDefinition } from '../plays/definition';
 import type { PlayStaticPipeline } from '../plays/static-pipeline';
+import type {
+  DurableCallStaleAfterSeconds,
+  PlayAuthoringCallOptions,
+  PlayAuthoringCsvOptions,
+  PlayAuthoringFetchOptions,
+  PlayAuthoringRuntimeStepOptions,
+  PlayAuthoringContractEdition,
+  PlayToolCallOptions,
+  PlayToolExecutionRequest,
+  PlayReceiptWaitMs,
+  PlayRuntimeTimeoutMs,
+} from '../plays/authoring-contract';
 import type {
   PlayDataset,
   PlayDatasetInput,
@@ -204,17 +216,13 @@ export interface HeartbeatRuntimeStepReceiptsInput {
   keys: string[];
   runId: string;
   runAttempt?: number | null;
-  leaseId: string;
+  leaseId?: string;
+  leaseIds?: string[];
 }
 
-export interface CsvOptions {
-  description?: string;
-  columns?: Record<string, string | readonly string[]>;
-  rename?: Record<string, string | readonly string[]>;
-  required?: readonly string[];
-}
+export type CsvOptions = PlayAuthoringCsvOptions;
 
-export interface DatasetOptions<TItem = Record<string, unknown>> {
+export interface RuntimeDatasetOptions<TItem = Record<string, unknown>> {
   description?: string;
   /**
    * Optional relative cache window for intentional reruns.
@@ -269,58 +277,30 @@ export interface DatasetOptions<TItem = Record<string, unknown>> {
   mode?: 'upsert' | 'net_new';
 }
 
-export type DatasetDefinitionOptions<TItem = Record<string, unknown>> = Omit<
-  DatasetOptions<TItem>,
-  'description'
->;
+export type RuntimeDatasetDefinitionOptions<TItem = Record<string, unknown>> =
+  Omit<RuntimeDatasetOptions<TItem>, 'description'>;
 
-export type DatasetRunOptions<TItem = Record<string, unknown>> = Pick<
-  DatasetOptions<TItem>,
+export type RuntimeDatasetRunOptions<TItem = Record<string, unknown>> = Pick<
+  RuntimeDatasetOptions<TItem>,
   'description' | 'key' | 'onRowError' | 'mode'
 >;
 
-export interface ToolCallOptions {
-  description?: string;
-  force?: boolean;
-  staleAfterSeconds?: number;
-  timeoutMs?: number;
-  receiptWaitMs?: number;
-}
+export type ToolCallOptions = PlayToolCallOptions;
+export type ToolExecutionRequest = PlayToolExecutionRequest;
 
-export interface ToolExecutionRequest {
-  id: string;
-  tool: string;
-  input: Record<string, unknown>;
-  description?: string;
-  force?: boolean;
-  staleAfterSeconds?: number;
-  timeoutMs?: number;
-  receiptWaitMs?: number;
-}
-
-export interface PlayCallOptions {
-  description?: string;
-  /**
-   * `child-workflow` is accepted only so the checker/runtime can emit the
-   * canonical CTX_RUN_PLAY_INLINE_ONLY migration diagnostic. It never starts a
-   * child workflow.
-   */
+export type PlayCallOptions = Omit<
+  PlayAuthoringCallOptions,
+  'execution' | 'timeoutMs'
+> & {
+  /** Legacy invalid spelling retained only for the stable migration error. */
   execution?: PlayCallExecution | 'child-workflow';
-  /**
-   * Parsed so source preflight and an untyped runtime call can return the
-   * canonical CTX_RUN_PLAY_INLINE_ONLY migration error. It is never honored.
-   */
+  /** Legacy invalid option retained only for the stable migration error. */
   timeoutMs?: number;
-}
+};
 
-export interface StepOptions {
-  semanticKey?: string;
-  staleAfterSeconds?: number;
-}
+export type RuntimeStepOptions = PlayAuthoringRuntimeStepOptions;
 
-export interface FetchOptions {
-  staleAfterSeconds?: number;
-}
+export type FetchOptions = PlayAuthoringFetchOptions;
 
 export interface ResolvedPlayExecution {
   playId: string;
@@ -501,6 +481,8 @@ export type IntegrationEventWaitHandler = {
 export interface ContextOptions {
   /** Immutable logical and physical execution identity for this context. */
   executionScope?: RunExecutionScope;
+  /** Authoring semantics pinned by the immutable artifact. */
+  authoringContractEdition?: PlayAuthoringContractEdition;
   /** Error shape pinned by the immutable play artifact; missing preserves legacy schema 0. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   /** Short-lived HMAC-signed internal token for tool callbacks. Required for cloud execution. */
@@ -588,7 +570,7 @@ export interface ContextOptions {
       staticPipeline?: PlayStaticPipeline | null;
       forceRefresh?: boolean;
       inputOffset?: number;
-      mode?: DatasetRunOptions['mode'];
+      mode?: RuntimeDatasetRunOptions['mode'];
     },
   ) => Promise<MapStartResult>;
   /**

package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts

@@ -6,40 +6,29 @@ import {
   // packed SDK's dist/bundling-sources graph, where only relative imports
   // resolve.
 } from '../plays/row-identity';
+import { resolveDurableCallCachePolicy } from './durable-call-policy';
+
+export {
+  DURABLE_CALL_STALE_AFTER_SECONDS_ERROR,
+  resolveDurableCallCachePolicy,
+} from './durable-call-policy';
+export type { DurableCallCachePolicy } from './durable-call-policy';
 
 export const DURABLE_CALL_CACHE_POLICY_VERSION = 'call-cache-v1';
 
 export type DurableCallKind = 'tool' | 'step' | 'fetch';
 
-function validateStaleAfterSeconds(staleAfterSeconds?: number | null): void {
-  if (staleAfterSeconds === undefined || staleAfterSeconds === null) {
-    return;
-  }
-  if (
-    !Number.isFinite(staleAfterSeconds) ||
-    !Number.isInteger(staleAfterSeconds) ||
-    staleAfterSeconds <= 0
-  ) {
-    throw new Error(
-      'staleAfterSeconds must be a positive whole number of seconds.',
-    );
-  }
-}
-
 export function durableCacheStaleBucket(input: {
   staleAfterSeconds?: number | null;
   nowMs?: number;
 }): string | null {
-  validateStaleAfterSeconds(input.staleAfterSeconds);
-  if (
-    input.staleAfterSeconds === undefined ||
-    input.staleAfterSeconds === null
-  ) {
+  const policy = resolveDurableCallCachePolicy(input.staleAfterSeconds);
+  if (policy.staleAfterSeconds === null) {
     return null;
   }
   const nowMs = input.nowMs ?? Date.now();
-  return `${input.staleAfterSeconds}:${Math.floor(
-    nowMs / (input.staleAfterSeconds * 1000),
+  return `${policy.staleAfterSeconds}:${Math.floor(
+    nowMs / (policy.staleAfterSeconds * 1000),
   )}`;
 }
 

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

@@ -0,0 +1,34 @@
+import {
+  PLAY_AUTHORING_FIELD_REGISTRY,
+  validatePlayAuthoringField,
+  type PlayAuthoringFieldPath,
+} from '../plays/authoring-contract';
+
+export const DURABLE_CALL_STALE_AFTER_SECONDS_ERROR =
+  PLAY_AUTHORING_FIELD_REGISTRY['ctx.tools.execute.staleAfterSeconds']
+    .errorMessage;
+
+export type DurableCallCachePolicy = {
+  forceRefresh: boolean;
+  staleAfterSeconds: number | null;
+};
+
+/** Normalize the public freshness contract shared by durable calls. */
+export function resolveDurableCallCachePolicy(
+  staleAfterSeconds?: number | null,
+  path: Extract<
+    PlayAuthoringFieldPath,
+    | 'ctx.tools.execute.staleAfterSeconds'
+    | 'ctx.step.staleAfterSeconds'
+    | 'ctx.fetch.staleAfterSeconds'
+  > = 'ctx.tools.execute.staleAfterSeconds',
+): DurableCallCachePolicy {
+  if (staleAfterSeconds === undefined || staleAfterSeconds === null) {
+    return { forceRefresh: false, staleAfterSeconds: null };
+  }
+  if (staleAfterSeconds === 0) {
+    return { forceRefresh: true, staleAfterSeconds: null };
+  }
+  validatePlayAuthoringField(path, staleAfterSeconds);
+  return { forceRefresh: false, staleAfterSeconds };
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-call-execution.ts

@@ -3,4 +3,5 @@
  * recognizes the historical `child-workflow` spelling so preflight can return
  * CTX_RUN_PLAY_INLINE_ONLY, but it is no longer a supported runtime option.
  */
-export type PlayCallExecution = 'inline';
+export type PlayCallExecution = Extract<PlayAuthoringCallExecution, 'inline'>;
+import type { PlayAuthoringCallExecution } from '../plays/authoring-contract';

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

@@ -0,0 +1,95 @@
+/**
+ * Wire contract for idempotent Runtime Postgres -> Convex Run Ledger delivery.
+ *
+ * Producers must use these builders and API boundaries must use these
+ * validators. Keeping the format here prevents the scheduler and runtime route
+ * from admitting different lifecycle-event keys.
+ */
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+
+function requireRunId(runId: string): void {
+  if (!runId.trim()) {
+    throw new Error('Run Ledger projection idempotency key requires a run id.');
+  }
+}
+
+function requireDeliveryKey(deliveryKey: string): void {
+  if (!UUID_PATTERN.test(deliveryKey)) {
+    throw new Error(
+      'Run Ledger projection delivery key must be a canonical UUID.',
+    );
+  }
+}
+
+export function buildRunLedgerStartIdempotencyKey(input: {
+  runId: string;
+  deliveryKey: string;
+}): string {
+  requireRunId(input.runId);
+  requireDeliveryKey(input.deliveryKey);
+  return `run-started:${input.runId}:${input.deliveryKey}`;
+}
+
+export function buildRunLedgerTerminalIdempotencyKey(input: {
+  runId: string;
+  deliveryKey: string;
+}): string {
+  requireRunId(input.runId);
+  requireDeliveryKey(input.deliveryKey);
+  return `run-terminal:${input.runId}:${input.deliveryKey}`;
+}
+
+/**
+ * Compatibility key for the one-row projector. The `run-terminal` prefix was
+ * historically used for every non-start row, including lifecycle events, so
+ * changing it during a retry could append the same fact twice across deploys.
+ */
+export function buildRunLedgerSingleEventIdempotencyKey(input: {
+  runId: string;
+  deliveryKey: string;
+}): string {
+  return buildRunLedgerTerminalIdempotencyKey(input);
+}
+
+export function buildRunLedgerEventsIdempotencyKey(input: {
+  runId: string;
+  deliveryDigest: string;
+}): string {
+  requireRunId(input.runId);
+  if (!SHA256_HEX_PATTERN.test(input.deliveryDigest)) {
+    throw new Error(
+      'Run Ledger projection delivery digest must be a SHA-256 hex value.',
+    );
+  }
+  return `run-events:${input.runId}:${input.deliveryDigest}`;
+}
+
+export function isValidRunLedgerStartIdempotencyKey(input: {
+  runId: string;
+  idempotencyKey: string;
+}): boolean {
+  const prefix = `run-started:${input.runId}:`;
+  return (
+    input.idempotencyKey.startsWith(prefix) &&
+    UUID_PATTERN.test(input.idempotencyKey.slice(prefix.length))
+  );
+}
+
+export function isValidRunLedgerAppendIdempotencyKey(input: {
+  runId: string;
+  idempotencyKey: string;
+}): boolean {
+  const terminalPrefix = `run-terminal:${input.runId}:`;
+  if (input.idempotencyKey.startsWith(terminalPrefix)) {
+    return UUID_PATTERN.test(input.idempotencyKey.slice(terminalPrefix.length));
+  }
+
+  const eventsPrefix = `run-events:${input.runId}:`;
+  return (
+    input.idempotencyKey.startsWith(eventsPrefix) &&
+    SHA256_HEX_PATTERN.test(input.idempotencyKey.slice(eventsPrefix.length))
+  );
+}

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

@@ -215,7 +215,8 @@ export type RuntimeReceiptAction =
       playName: string;
       runId: string;
       runAttempt?: number | null;
-      leaseId: string;
+      leaseId?: string;
+      leaseIds?: string[];
       keys: string[];
     };
 

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

@@ -5799,15 +5799,30 @@ export async function heartbeatRuntimeWorkReceipts(
     playName: string;
     runId: string;
     runAttempt?: number | null;
-    leaseId: string;
+    leaseId?: string;
+    leaseIds?: string[];
     keys: string[];
     leaseTtlMs?: number | null;
   },
 ): Promise<Array<WorkReceipt | null>> {
-  const keys = input.keys.map((key) => key.trim()).filter(Boolean);
+  if (
+    input.leaseIds !== undefined &&
+    input.leaseIds.length !== input.keys.length
+  ) {
+    throw new Error(
+      `Runtime receipt bulk heartbeat requires one lease ID per key. Received ${input.leaseIds.length} lease IDs for ${input.keys.length} keys.`,
+    );
+  }
+  const entries = input.keys
+    .map((key, index) => ({
+      key: key.trim(),
+      leaseId: input.leaseIds?.[index]?.trim() || input.leaseId?.trim() || '',
+    }))
+    .filter((entry) => Boolean(entry.key));
+  const keys = entries.map((entry) => entry.key);
   if (keys.length === 0) return [];
-  const leaseId = input.leaseId.trim();
-  if (!leaseId) return keys.map(() => null);
+  const leaseIds = entries.map((entry) => entry.leaseId);
+  if (leaseIds.some((leaseId) => !leaseId)) return keys.map(() => null);
   const runAttempt = normalizeRuntimeRunAttempt(input.runAttempt);
   const leaseTtlMs = normalizeRuntimeLeaseTtlMs(
     input.leaseTtlMs,
@@ -5824,8 +5839,10 @@ export async function heartbeatRuntimeWorkReceipts(
       const { rows } = await client.query<Record<string, unknown>>(
         `
       WITH input_keys AS (
-        SELECT key_values.key_hex, key_values.ord
+        SELECT key_values.key_hex, lease_values.lease_id, key_values.ord
         FROM unnest($1::text[]) WITH ORDINALITY AS key_values(key_hex, ord)
+        JOIN unnest($3::text[]) WITH ORDINALITY AS lease_values(lease_id, ord)
+          ON lease_values.ord = key_values.ord
       ),
       renewed AS (
         UPDATE ${workReceiptTable(session)} AS target
@@ -5837,7 +5854,7 @@ export async function heartbeatRuntimeWorkReceipts(
              receiptTable: 'target',
              ownerRunIdSql: '$2::text',
              ownerRunAttemptSql: '$5',
-             leaseIdSql: '$3::text',
+             leaseIdSql: 'input_keys.lease_id',
            })}
         RETURNING target.k,
                   target.status,
@@ -5888,7 +5905,7 @@ export async function heartbeatRuntimeWorkReceipts(
         [
           keys.map(workReceiptKeyHex),
           input.runId,
-          leaseId,
+          leaseIds,
           leaseTtlMs,
           runAttempt,
         ],

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

@@ -1,4 +1,4 @@
-export const PLAY_RUNTIME_CONTRACT = 3;
+export const PLAY_RUNTIME_CONTRACT = 4;
 export const PLAY_RUNTIME_CONTRACT_MIN_SUPPORTED = 1;
 export const PLAY_RUNTIME_CONTRACT_HEADER = 'x-deepline-runtime-contract';
 /**
@@ -25,6 +25,13 @@ export function resolvePlayRuntimeTransportAttemptId(
 }
 
 export const RUNTIME_CONTRACT_CHANGELOG = [
+  {
+    contract: 4,
+    changed:
+      'Runtime receipt heartbeat requests can carry one positional lease ID per receipt key.',
+    compatOwner: 'runtime',
+    compatRemoval: 'contract 3 runtime lane drain',
+  },
   {
     contract: 3,
     changed:

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-store-adapter.ts

@@ -236,13 +236,13 @@ export class RuntimeReceiptStoreAdapter {
         ),
       heartbeatRuntimeStepReceipts: (input) =>
         writeMany(
-          input.keys.map((key) => ({
+          input.keys.map((key, index) => ({
             kind: 'heartbeat' as const,
             input: {
               key,
               runId: input.runId,
               runAttempt: input.runAttempt,
-              leaseId: input.leaseId,
+              leaseId: input.leaseIds?.[index] ?? input.leaseId ?? '',
             },
           })),
         ),
@@ -387,7 +387,6 @@ function receiptCommandBatchKey(command: ReceiptCommand): string {
         command.kind,
         command.input.runId,
         command.input.runAttempt ?? null,
-        command.input.leaseId,
       ]);
     case 'acquire_execution_lock':
     case 'release_execution_lock':
@@ -491,11 +490,15 @@ async function sendReceiptCommands(input: {
         ReceiptCommand,
         { kind: 'heartbeat' }
       >[];
+      const leaseIds = commands.map((command) => command.input.leaseId);
+      const sharedLeaseId = leaseIds.every((leaseId) => leaseId === leaseIds[0])
+        ? leaseIds[0]
+        : undefined;
       return await heartbeatRuntimeStepReceiptsViaAppRuntime(input.context, {
         playName: input.playName,
         runId: first.input.runId,
         runAttempt: first.input.runAttempt,
-        leaseId: first.input.leaseId,
+        ...(sharedLeaseId ? { leaseId: sharedLeaseId } : { leaseIds }),
         keys: commands.map((command) => command.input.key),
       });
     }

package/dist/bundling-sources/shared_libs/play-runtime/secret-capability.ts

@@ -1,28 +1,36 @@
+import type {
+  PlaySecretAuth,
+  PlaySecretAwareRequestInit,
+  PlaySecretHandle,
+} from '../plays/authoring-contract';
+
 const SECRET_HANDLE_BRAND = Symbol.for('deepline.secret.handle');
 const SECRET_AUTH_BRAND = Symbol.for('deepline.secret.auth');
 const SECRET_HANDLE_MARKER_RE = /\[secret:[A-Z0-9_ -]+\]/i;
 
-export type SecretHandle = {
+export type SecretHandle = PlaySecretHandle & {
   readonly [SECRET_HANDLE_BRAND]: true;
   readonly name: string;
   toString(): string;
   toJSON(): never;
 };
 
-export type SecretAuth =
-  | {
-      readonly [SECRET_AUTH_BRAND]: true;
-      readonly kind: 'bearer';
-      readonly secret: SecretHandle;
-    }
-  | {
-      readonly [SECRET_AUTH_BRAND]: true;
-      readonly kind: 'header';
-      readonly header: string;
-      readonly secret: SecretHandle;
-    };
+export type SecretAuth = PlaySecretAuth &
+  (
+    | {
+        readonly [SECRET_AUTH_BRAND]: true;
+        readonly kind: 'bearer';
+        readonly secret: SecretHandle;
+      }
+    | {
+        readonly [SECRET_AUTH_BRAND]: true;
+        readonly kind: 'header';
+        readonly header: string;
+        readonly secret: SecretHandle;
+      }
+  );
 
-export type SecretAwareRequestInit = RequestInit & {
+export type SecretAwareRequestInit = PlaySecretAwareRequestInit & {
   auth?: SecretAuth;
 };
 
@@ -70,7 +78,7 @@ export function createSecretHandle(name: string): SecretHandle {
         `Secret ${name} cannot be serialized. Use an approved ctx.secrets helper.`,
       );
     },
-  };
+  } as unknown as SecretHandle;
 }
 
 export function createBearerSecretAuth(secret: SecretHandle): SecretAuth {

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -1,4 +1,5 @@
 import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
+import type { PlayAuthoringContractEdition } from './authoring-contract';
 
 export type PlayPackageImport = {
   name: string;
@@ -25,6 +26,8 @@ export type PlayArtifactCompatibility = {
   runtimeBackend?: string | null;
   /** Missing preserves the legacy schema used before this field existed. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
+  /** Missing preserves edition 1 for artifacts created before authoring contracts were pinned. */
+  authoringContractEdition?: PlayAuthoringContractEdition;
 };
 
 /** The only executable Play artifact contract. */