deepline 0.2.13 → 0.2.15

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,
@@ -208,14 +220,9 @@ export interface HeartbeatRuntimeStepReceiptsInput {
   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.
@@ -270,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;
@@ -502,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. */
@@ -589,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-api.ts

@@ -5844,17 +5844,21 @@ export async function heartbeatRuntimeWorkReceipts(
         JOIN unnest($3::text[]) WITH ORDINALITY AS lease_values(lease_id, ord)
           ON lease_values.ord = key_values.ord
       ),
+      unique_inputs AS (
+        SELECT DISTINCT key_hex, lease_id
+          FROM input_keys
+      ),
       renewed AS (
         UPDATE ${workReceiptTable(session)} AS target
            SET lease_expires_at = now() + ($4::double precision * interval '1 millisecond'),
                updated_at = now()
-          FROM input_keys
-         WHERE target.k = decode(input_keys.key_hex, 'hex')
+          FROM unique_inputs
+         WHERE target.k = decode(unique_inputs.key_hex, 'hex')
            AND ${workReceiptHeartbeatPredicateSql({
              receiptTable: 'target',
              ownerRunIdSql: '$2::text',
              ownerRunAttemptSql: '$5',
-             leaseIdSql: 'input_keys.lease_id',
+             leaseIdSql: 'unique_inputs.lease_id',
            })}
         RETURNING target.k,
                   target.status,
@@ -5867,8 +5871,7 @@ export async function heartbeatRuntimeWorkReceipts(
                   target.lease_owner_run_id,
                   target.lease_owner_attempt,
                   target.lease_expires_at,
-                  target.updated_at,
-                  input_keys.ord
+                  target.updated_at
       ),
       returned AS (
         SELECT renewed.k,
@@ -5885,7 +5888,9 @@ export async function heartbeatRuntimeWorkReceipts(
                renewed.updated_at,
                input_keys.ord
           FROM input_keys
-          LEFT JOIN renewed ON renewed.ord = input_keys.ord
+          LEFT JOIN renewed
+            ON renewed.k = decode(input_keys.key_hex, 'hex')
+           AND renewed.lease_id = input_keys.lease_id
       )
       SELECT convert_from(returned.k, 'UTF8') AS k,
              returned.status,

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

@@ -25,7 +25,10 @@ import {
   skipRuntimeStepReceiptViaAppRuntime,
   type WorkerRuntimeApiContext,
 } from './app-runtime-api';
-import { RuntimeReceiptWriter } from './runtime-receipt-writer';
+import {
+  RuntimeReceiptWriter,
+  RuntimeReceiptWriterResultCountError,
+} from './runtime-receipt-writer';
 
 type ReceiptOutput =
   | RuntimeStepReceipt
@@ -490,17 +493,43 @@ async function sendReceiptCommands(input: {
         ReceiptCommand,
         { kind: 'heartbeat' }
       >[];
-      const leaseIds = commands.map((command) => command.input.leaseId);
+      const uniqueCommands: (typeof commands)[number][] = [];
+      const uniqueIndexByIdentity = new Map<string, number>();
+      const originalToUniqueIndex = commands.map((command) => {
+        const identity = JSON.stringify([
+          command.input.key,
+          command.input.leaseId,
+        ]);
+        const existingIndex = uniqueIndexByIdentity.get(identity);
+        if (existingIndex !== undefined) return existingIndex;
+        const uniqueIndex = uniqueCommands.length;
+        uniqueCommands.push(command);
+        uniqueIndexByIdentity.set(identity, uniqueIndex);
+        return uniqueIndex;
+      });
+      const leaseIds = uniqueCommands.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,
-        ...(sharedLeaseId ? { leaseId: sharedLeaseId } : { leaseIds }),
-        keys: commands.map((command) => command.input.key),
-      });
+      const uniqueResults = await heartbeatRuntimeStepReceiptsViaAppRuntime(
+        input.context,
+        {
+          playName: input.playName,
+          runId: first.input.runId,
+          runAttempt: first.input.runAttempt,
+          ...(sharedLeaseId ? { leaseId: sharedLeaseId } : { leaseIds }),
+          keys: uniqueCommands.map((command) => command.input.key),
+        },
+      );
+      if (uniqueResults.length !== uniqueCommands.length) {
+        throw new RuntimeReceiptWriterResultCountError(
+          uniqueCommands.length,
+          uniqueResults.length,
+        );
+      }
+      return originalToUniqueIndex.map(
+        (uniqueIndex) => uniqueResults[uniqueIndex]!,
+      );
     }
     case 'acquire_execution_lock':
       return [

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. */