deepline 0.2.13 → 0.2.14

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