deepline 0.3.59 → 0.3.61

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -7,10 +7,10 @@ import type { ToolExecutionErrorSchemaVersion } from './tool-execution-error';
 import type { PlayDataset, PlayDatasetInput, PlayDatasetRow } from './dataset';
 
 export const LEGACY_PLAY_AUTHORING_CONTRACT_EDITION = 1 as const;
-export const PLAY_AUTHORING_CONTRACT_EDITION = 5 as const;
+export const PLAY_AUTHORING_CONTRACT_EDITION = 6 as const;
 export const PLAY_AUTHORING_INPUT_SCHEMA_SNAPSHOT_EDITION = 3 as const;
 export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
-  1, 2, 3, 4, 5,
+  1, 2, 3, 4, 5, 6,
 ] as const;
 
 export type PlayAuthoringContractEdition =
@@ -59,6 +59,14 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     newWritesEnd: null,
     readerRemoval: null,
   },
+  {
+    edition: 6,
+    changed:
+      'Adds static cron input and rejects unknown definePlay and binding fields during new admission. Editions 1–5 retain their admitted binding semantics.',
+    compatibilityOwner: 'Plays Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
 ] as const;
 
 /**
@@ -310,7 +318,11 @@ export type PlayTriggersSummary = {
   sqlListeners?: PlayTriggerSqlListenerSummary[];
   /** Present when the play has at least one sqlListener trigger. */
   sqlListenerEvent?: PlayTriggerSqlListenerEventSummary;
-  cron?: { schedule: string; timezone?: string };
+  cron?: {
+    schedule: string;
+    timezone?: string;
+    input?: Record<string, unknown>;
+  };
   webhook?: true;
 };
 
@@ -344,9 +356,11 @@ export function derivePlayTriggersSummary(
     };
   }
   if (bindings.cron?.schedule) {
-    summary.cron = bindings.cron.timezone
-      ? { schedule: bindings.cron.schedule, timezone: bindings.cron.timezone }
-      : { schedule: bindings.cron.schedule };
+    summary.cron = {
+      schedule: bindings.cron.schedule,
+      ...(bindings.cron.timezone ? { timezone: bindings.cron.timezone } : {}),
+      ...(bindings.cron.input ? { input: bindings.cron.input } : {}),
+    };
   }
   if (bindings.webhook) summary.webhook = true;
   return summary.sqlListeners || summary.cron || summary.webhook
@@ -377,15 +391,74 @@ export type PlayAuthoringAstBindings = {
     };
     auth?: PlayStandardWebhookAuth;
   };
-  cron?: { schedule: string; timezone?: string };
+  cron?: {
+    schedule: string;
+    timezone?: string;
+    /** Static JSON object supplied to every run started by this cron binding. */
+    input?: Record<string, unknown>;
+  };
   sqlListeners?: PlayAuthoringAstSqlListenerDeclaration[];
   invalidSqlListenerSingular?: boolean;
   invalidSqlListenerShape?: boolean;
   secrets?: string[];
 };
 
+/**
+ * Static binding vocabulary. The AST adapter reads this rather than carrying
+ * a second allowlist, so `plays check` and publish reject typos consistently.
+ * Existing revisions are never re-admitted merely because this expands.
+ */
+export const PLAY_AUTHORING_BINDING_FIELDS = {
+  root: [
+    'billing',
+    'compatibility',
+    'cron',
+    'inline',
+    'runtime',
+    'secrets',
+    'sqlListeners',
+    'webhook',
+  ],
+  cron: ['schedule', 'timezone', 'input'],
+  webhook: ['auth', 'hmac'],
+  sqlListener: [
+    'id',
+    'tool',
+    'stream',
+    'where',
+    'table',
+    'monitor',
+    'output',
+    'operations',
+  ],
+} as const;
+
+/** Fields allowed in the object form and third argument of `definePlay`. */
+export const PLAY_AUTHORING_DEFINE_PLAY_OPTION_FIELDS = [
+  'id',
+  'name',
+  'description',
+  'input',
+  'run',
+  'bindings',
+  ...PLAY_AUTHORING_BINDING_FIELDS.root,
+] as const;
+
+/**
+ * Static cron input must be an object because the scheduler accepts a JSON
+ * object. It is tied to the Play handler input so TypeScript rejects missing
+ * required fields and incompatible values before the Play reaches `check`.
+ */
+export type PlayAuthoringCronInput<TInput> = TInput extends readonly unknown[]
+  ? never
+  : TInput extends object
+    ? TInput
+    : never;
+
 /** The one public type for options accepted by definePlay. */
-export type PlayAuthoringBindings = {
+export type PlayAuthoringBindings<
+  TInput = Record<string, unknown>,
+> = {
   description?: string;
   compatibility?: {
     toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
@@ -420,6 +493,8 @@ export type PlayAuthoringBindings = {
   cron?: {
     schedule: string;
     timezone?: string;
+    /** Static JSON object supplied to every run started by this cron binding. */
+    input?: PlayAuthoringCronInput<TInput>;
   };
   sqlListeners?: PlaySqlListenerDeclaration[];
   secrets?: readonly string[];
@@ -495,7 +570,7 @@ export type PlaySecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
   /** Ordinary request headers, recorded in the durable receipt with any resolved Play secret value redacted. Prefer `auth` for credentials: it enforces HTTPS and keeps the auth header out of the receipt. */
   headers?: HeadersInit;
   /**
-   * One or more credentialed headers for this request. Pass a single `ctx.secrets` auth for the common case, or an array when an API requires multiple credentialed headers — for example, Supabase with both `apikey` and `Authorization`. Auth-helper requests require HTTPS and omit the credential from the durable receipt. Each auth entry must target a distinct header.
+   * One or more credentialed headers for this request. Pass a single `ctx.secrets` auth for the common case, or an array when an API requires multiple credentialed headers. Auth-helper requests require HTTPS and omit the credential from the durable receipt. Each auth entry must target a distinct header.
    */
   auth?: PlaySecretAuthInput;
 };
@@ -522,10 +597,10 @@ export type PlayAuthoringDefineConfig<
   description?: string;
   input: PlayAuthoringInputContract<TInput>;
   run: (ctx: TContext, input: TInput) => Promise<TOutput>;
-  bindings?: PlayAuthoringBindings;
-  billing?: PlayAuthoringBindings['billing'];
-  runtime?: PlayAuthoringBindings['runtime'];
-  compatibility?: PlayAuthoringBindings['compatibility'];
+  bindings?: PlayAuthoringBindings<TInput>;
+  billing?: PlayAuthoringBindings<TInput>['billing'];
+  runtime?: PlayAuthoringBindings<TInput>['runtime'];
+  compatibility?: PlayAuthoringBindings<TInput>['compatibility'];
 };
 
 /** Shared callable-plus-handle shape returned by `definePlay`. */
@@ -536,9 +611,9 @@ export type PlayAuthoringDefinedPlay<
   THandle extends object,
 > = ((ctx: TContext, input: TInput) => Promise<TOutput>) &
   THandle & {
-    readonly bindings?: PlayAuthoringBindings;
-    readonly runtime?: PlayAuthoringBindings['runtime'];
-    readonly compatibility?: PlayAuthoringBindings['compatibility'];
+    readonly bindings?: PlayAuthoringBindings<TInput>;
+    readonly runtime?: PlayAuthoringBindings<TInput>['runtime'];
+    readonly compatibility?: PlayAuthoringBindings<TInput>['compatibility'];
     readonly playName: string;
   };
 
@@ -1428,6 +1503,24 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'bindings.cron.timezone must be a valid non-empty IANA timezone string.',
   },
+  'bindings.cron.input': {
+    schema: Type.Object({}, { additionalProperties: true }),
+    fixtures: {
+      valid: { apply: true },
+      invalid: ['apply'],
+      absent: undefined,
+      unresolved: ['cronInput'],
+      edition1: undefined,
+    },
+    referenceType: 'Record<string, unknown>',
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_binding_invalid',
+    description:
+      'Static JSON object passed to every run created by this cron binding.',
+    errorMessage:
+      'bindings.cron.input must be a static JSON object (no variables, spreads, or functions).',
+  },
   'bindings.sqlListeners': {
     schema: Type.Array(Type.Object({}, { additionalProperties: true })),
     fixtures: {
@@ -2619,14 +2712,15 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  readonly timeoutMs?: PlayRuntimeTimeoutMs;',
   '  readonly receiptWaitMs?: PlayReceiptWaitMs;',
   '};',
-  'export type PlayBindings = {',
+  'export type PlayCronInput<TInput> = TInput extends readonly unknown[] ? never : TInput extends object ? TInput : never;',
+  'export type PlayBindings<TInput = Record<string, unknown>> = {',
   `  description?: ${cloudReferenceType('description')};`,
   `  compatibility?: { toolErrorSchemaVersion?: ${cloudReferenceType('compatibility.toolErrorSchemaVersion')}; toolResponseReceiptRevision?: ${cloudReferenceType('compatibility.toolResponseReceiptRevision')} };`,
   `  inline?: ${cloudReferenceType('inline')};`,
   `  billing?: { maxCreditsPerRun?: ${cloudReferenceType('billing.maxCreditsPerRun')} };`,
   `  runtime?: { timeout?: ${cloudReferenceType('runtime.timeout')}; size?: ${cloudReferenceType('runtime.size')} };`,
   `  webhook?: { hmac?: { algorithm?: ${cloudReferenceType('bindings.webhook.hmac.algorithm')}; header?: ${cloudReferenceType('bindings.webhook.hmac.header')}; secretEnv: ${cloudReferenceType('bindings.webhook.hmac.secretEnv')} }; auth?: { type: ${cloudReferenceType('bindings.webhook.auth.type')}; headerFamily: ${cloudReferenceType('bindings.webhook.auth.headerFamily')}; signingSecrets: readonly ${cloudReferenceType('bindings.webhook.auth.signingSecrets[]')}[]; toleranceSeconds?: ${cloudReferenceType('bindings.webhook.auth.toleranceSeconds')} } };`,
-  `  cron?: { schedule: ${cloudReferenceType('bindings.cron.schedule')}; timezone?: ${cloudReferenceType('bindings.cron.timezone')} };`,
+  `  cron?: { schedule: ${cloudReferenceType('bindings.cron.schedule')}; timezone?: ${cloudReferenceType('bindings.cron.timezone')}; input?: PlayCronInput<TInput> };`,
   '  sqlListeners?: readonly SqlListenerDeclaration[];',
   `  secrets?: readonly ${cloudReferenceType('bindings.secrets[]')}[];`,
   '};',
@@ -2692,6 +2786,8 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  log(message: string): void;',
   `  sleep(ms: ${cloudReferenceType('ctx.sleep.ms')}): Promise<void>;`,
   '}',
-  "export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = { id: string; description?: string; input: PlayInputContract<TInput>; run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>; bindings?: PlayBindings; billing?: PlayBindings['billing']; runtime?: PlayBindings['runtime']; compatibility?: PlayBindings['compatibility'] };",
-  "export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>) & { readonly name: string; readonly __inputType?: TInput; readonly __outputType?: TOutput; readonly runtime?: PlayBindings['runtime']; readonly compatibility?: PlayBindings['compatibility'] };",
+  "export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = { id: string; description?: string; input: PlayInputContract<TInput>; run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>; bindings?: PlayBindings<TInput>; billing?: PlayBindings<TInput>['billing']; runtime?: PlayBindings<TInput>['runtime']; compatibility?: PlayBindings<TInput>['compatibility'] };",
+  "export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>) & { readonly name: string; readonly __inputType?: TInput; readonly __outputType?: TOutput; readonly bindings?: PlayBindings<TInput>; readonly runtime?: PlayBindings<TInput>['runtime']; readonly compatibility?: PlayBindings<TInput>['compatibility'] };",
+  'export type PlayHandlerInput<THandler> = THandler extends (context: DeeplinePlayRuntimeContext, input: infer TInput) => Promise<PlayReturnObject> ? TInput : never;',
+  'export type PlayHandlerOutput<THandler> = THandler extends (context: DeeplinePlayRuntimeContext, input: unknown) => Promise<infer TOutput extends PlayReturnObject> ? TOutput : never;',
 ] as const;

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

@@ -41,7 +41,8 @@ import { createPlayInputContract } from './input-contract-definition';
 
 export type { ToolExecuteResult } from './tool-result-types';
 
-export type PlayBindings = PlayAuthoringBindings;
+export type PlayBindings<TInput = Record<string, unknown>> =
+  PlayAuthoringBindings<TInput>;
 export type SqlListenerOperation = PlaySqlListenerOperation;
 export type SqlListenerFilterScalar = PlaySqlListenerFilterScalar;
 export type SqlListenerFilterOperator = PlaySqlListenerFilterOperator;
@@ -135,14 +136,14 @@ export type DefinePlayConfig<
   TOutput extends PlayReturnObject,
 > = PlayAuthoringDefineConfig<TInput, TOutput, DeeplinePlayRuntimeContext>;
 
-export type PlayMetadata = {
+export type PlayMetadata<TInput = Record<string, unknown>> = {
   name: string;
   description?: string;
-  bindings?: PlayBindings;
+  bindings?: PlayBindings<TInput>;
   inputSchema?: Record<string, unknown>;
-  billing?: PlayBindings['billing'];
-  runtime?: PlayBindings['runtime'];
-  compatibility?: PlayBindings['compatibility'];
+  billing?: PlayBindings<TInput>['billing'];
+  runtime?: PlayBindings<TInput>['runtime'];
+  compatibility?: PlayBindings<TInput>['compatibility'];
 };
 
 export type CoreNamedPlayHandle<
@@ -170,6 +171,20 @@ export type DefinedPlay<
   THandle
 >;
 
+type PlayHandlerInput<THandler> = THandler extends (
+  context: DeeplinePlayRuntimeContext,
+  input: infer TInput,
+) => Promise<PlayReturnObject>
+  ? TInput
+  : never;
+
+type PlayHandlerOutput<THandler> = THandler extends (
+  context: DeeplinePlayRuntimeContext,
+  input: unknown,
+) => Promise<infer TOutput extends PlayReturnObject>
+  ? TOutput
+  : never;
+
 export const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
 
 class PlayCoreConditionalStepResolver<
@@ -317,7 +332,7 @@ export function createDefinedPlay<
   maybeFn:
     | ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>)
     | undefined,
-  maybeBindings: PlayBindings | undefined,
+  maybeBindings: PlayBindings<TInput> | undefined,
   createHandle: (name: string) => THandle,
 ): DefinedPlay<TInput, TOutput, THandle> {
   const config =
@@ -368,7 +383,7 @@ export function createDefinedPlay<
     );
   }
 
-  const metadata: PlayMetadata = {
+  const metadata: PlayMetadata<TInput> = {
     name,
     ...(description ? { description } : {}),
     ...(config.bindings ? { bindings: config.bindings } : {}),
@@ -426,18 +441,36 @@ export function createDefinedPlay<
 export function definePlay<TInput, TOutput extends PlayReturnObject>(
   config: DefinePlayConfig<TInput, TOutput>,
 ): DefinedPlay<TInput, TOutput>;
-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: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
-  bindings?: PlayBindings,
-): DefinedPlay<TInput, TOutput>;
+  fn: (
+    context: DeeplinePlayRuntimeContext,
+    input: unknown,
+  ) => Promise<TOutput>,
+  bindings: PlayBindings<never> & {
+    readonly sqlListeners: readonly SqlListenerDeclaration[];
+  },
+): DefinedPlay<unknown, TOutput>;
+/* eslint-disable @typescript-eslint/no-explicit-any -- This constraint must infer a concrete contravariant handler input. */
+export function definePlay<
+  THandler extends (
+  context: DeeplinePlayRuntimeContext,
+    input: any,
+  ) => Promise<PlayReturnObject>,
+>(
+  name: string,
+  fn: THandler,
+  bindings?: PlayBindings<NoInfer<PlayHandlerInput<THandler>>>,
+): DefinedPlay<PlayHandlerInput<THandler>, PlayHandlerOutput<THandler>>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
 export function definePlay<TInput, TOutput extends PlayReturnObject>(
   nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
   maybeFn?: (
     ctx: DeeplinePlayRuntimeContext,
     input: TInput,
   ) => Promise<TOutput>,
-  maybeBindings?: PlayBindings,
+  maybeBindings?: PlayBindings<TInput>,
 ): DefinedPlay<TInput, TOutput> {
   return createDefinedPlay(nameOrConfig, maybeFn, maybeBindings, (name) =>
     createUnavailableNamedPlayHandle<TInput, TOutput>(name),