deepline 0.3.49 → 0.3.51

package/dist/bundling-sources/shared_libs/play-runtime/test-runtime-seams.ts

@@ -36,8 +36,6 @@ type ValidatedRuntimeTestFaultHeader =
 export type RuntimeTestPolicyOverrides = {
   /** Opt-in bounded runner map latency profile for local/preview diagnosis. */
   mapLatencyProfile?: boolean;
-  /** Exercise provider pacing during fixture runs without dispatching provider traffic. */
-  enforceFixtureProviderPacing?: boolean;
   receiptLeaseTtlMs?: number;
   sheetAttemptLeaseMs?: number;
   heartbeatIntervalMs?: number;
@@ -258,8 +256,7 @@ function parseRuntimeTestPolicyOverrides(
     (key) =>
       !RUNTIME_TEST_POLICY_MS_FIELDS.has(key) &&
       key !== 'workBudgetYieldLimits' &&
-      key !== 'mapLatencyProfile' &&
-      key !== 'enforceFixtureProviderPacing',
+      key !== 'mapLatencyProfile',
   );
   if (unknownKeys.length > 0) {
     return {
@@ -276,16 +273,6 @@ function parseRuntimeTestPolicyOverrides(
     }
     overrides.mapLatencyProfile = record.mapLatencyProfile;
   }
-  if ('enforceFixtureProviderPacing' in record) {
-    if (typeof record.enforceFixtureProviderPacing !== 'boolean') {
-      return {
-        error:
-          'testPolicyOverrides.enforceFixtureProviderPacing must be a boolean.',
-      };
-    }
-    overrides.enforceFixtureProviderPacing =
-      record.enforceFixtureProviderPacing;
-  }
   for (const field of RUNTIME_TEST_POLICY_MS_FIELDS) {
     if (!(field in record)) continue;
     const parsed = readPositiveIntegerField({

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

@@ -105,15 +105,25 @@ export type ToolResultReceipts = {
   }): Promise<void>;
 };
 
+export type AlwaysFreshToolCallDispatch = {
+  call: ToolCallInput;
+  /** An always-fresh call must not claim a provider idempotency identity. */
+  providerOperationKey: null;
+  /** Receiptless means structurally absent, not a nullable lease. */
+  receipt?: never;
+};
+
+export type ReceiptBackedToolCallDispatch = {
+  call: ToolCallInput;
+  providerOperationKey: string;
+  receipt: ToolCallReceiptLease;
+};
+
 /** Direct and map execution are Adapter choices, never separate public jobs. */
 export type ToolCallDispatcher = {
-  dispatch(input: {
-    call: ToolCallInput;
-    /** Null means the adapter must not emit a provider-idempotency identity. */
-    providerOperationKey: string | null;
-    /** Null means this is a receiptless, always-fresh physical call. */
-    receipt: ToolCallReceiptLease | null;
-  }): Promise<ToolExecuteResult>;
+  dispatch(
+    input: AlwaysFreshToolCallDispatch | ReceiptBackedToolCallDispatch,
+  ): Promise<ToolExecuteResult>;
 };
 
 export type ToolCallDependencies = {

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

@@ -160,7 +160,6 @@ export function createToolCallJob(
         return await dependencies.dispatcher.dispatch({
           call: input,
           providerOperationKey: null,
-          receipt: null,
         });
       }
 

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

@@ -7,9 +7,11 @@ 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 = 4 as const;
+export const PLAY_AUTHORING_CONTRACT_EDITION = 5 as const;
 export const PLAY_AUTHORING_INPUT_SCHEMA_SNAPSHOT_EDITION = 3 as const;
-export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [1, 2, 3, 4] as const;
+export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
+  1, 2, 3, 4, 5,
+] as const;
 
 export type PlayAuthoringContractEdition =
   (typeof SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS)[number];
@@ -49,6 +51,47 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     newWritesEnd: null,
     readerRemoval: null,
   },
+  {
+    edition: 5,
+    changed:
+      'ctx.fetch throws a typed, redacted CtxFetchHttpError for non-2xx responses. Editions 1–4 continue to return the response record for every HTTP status.',
+    compatibilityOwner: 'Plays Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
+] as const;
+
+/**
+ * Customer-visible runtime capabilities that are not expressible as one
+ * `ctx.*` signature. The generated authoring reference renders this inventory
+ * directly; add a row here alongside any new supported runtime global or
+ * execution-boundary guarantee.
+ */
+export const PLAY_AUTHORING_RUNTIME_CAPABILITIES = [
+  {
+    capability: 'Durable external I/O',
+    surface: '`ctx.fetch`, `ctx.tools.execute`, `ctx.step`, `ctx.runPlay`',
+    contract:
+      'Use a `ctx.*` primitive for external work. Each primitive owns durable receipt identity and replay; raw I/O in an authored handler does not.',
+  },
+  {
+    capability: 'Web Crypto',
+    surface: '`crypto.subtle`',
+    contract:
+      'WebCrypto is available for standards-based signing, verification, encryption, and key import. Keep private material in `ctx.secrets`; `docs-examples/sdk-v2/github-app-jwt.play.ts` signs an RS256 GitHub App JWT and uses `staleAfterSeconds: 0` for its time-varying auth exchange.',
+  },
+  {
+    capability: 'Workspace secrets',
+    surface: '`ctx.secrets.get`, `.bearer`, `.header`',
+    contract:
+      'Declare the secret at the Play boundary, read it only at runtime, and never return or log it. Secret-bearing HTTP requests require HTTPS.',
+  },
+  {
+    capability: 'Freshness',
+    surface: '`staleAfterSeconds` on durable calls',
+    contract:
+      'This is call-receipt freshness: omitted/null reuses forever, zero always executes, and a positive integer is a TTL in seconds. It never changes dataset or request identity.',
+  },
 ] as const;
 
 export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
@@ -78,6 +121,7 @@ export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
   'play_authoring_fetch_secret_requires_tls',
   'play_authoring_fetch_idempotency_required',
   'play_authoring_fetch_key_reused_in_loop',
+  'play_authoring_fetch_http_error_branch',
   'play_authoring_binding_invalid',
   'play_authoring_input_schema_unresolved',
   'tool_response_raw_access',
@@ -842,12 +886,24 @@ export type PlayAuthoringRuntimeStepOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
 
+/**
+ * Durable freshness for one `ctx.fetch` call. The key identifies the request;
+ * `staleAfterSeconds` controls when that completed request may be reused across
+ * Play runs. Omit it (or pass `null`) to reuse indefinitely, pass `0` to
+ * execute on every new run, or pass a positive number of seconds for a TTL.
+ *
+ * Use this for polling or periodically refreshing one external resource. It
+ * does not change dataset row identity.
+ *
+ */
 export type PlayAuthoringFetchOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
+  /** Run through Deepline's guarded outbound path without retaining a response receipt or checkpoint. Use this for short-lived credential exchanges or other response data that should stay in the running Play only. */
+  transient?: boolean;
 };
 
 /**
- * The value `ctx.fetch(...)` resolves to: a plain durable record, not a WHATWG `Response`. The body is read once at request time so the call can be checkpointed and replayed, so `bodyText` and `json` are already-materialized properties. There is no `.json()`, `.text()`, or `.body` to await — `await res.json()` is a type error, not a typing problem.
+ * A durable response record, not a WHATWG `Response`: read the already-materialized `bodyText` and `json` properties; do not call `.json()`, `.text()`, or `.body`.
  *
  * @sdkReference runtime 175 PlayFetchResponse
  */
@@ -870,6 +926,55 @@ export type PlayAuthoringFetchResponse = {
   json: unknown | null;
 };
 
+/**
+ * Edition 5+ `ctx.fetch` error for a non-2xx response. Its full readable body is secret-redacted; editions 1–4 retain `PlayFetchResponse { ok: false }`.
+ *
+ * @sdkReference runtime 178 CtxFetchHttpError
+ */
+export class CtxFetchHttpError extends Error {
+  /**
+   * Play source and the runtime are separately bundled. Recognize the stable
+   * public error code so `instanceof` works across that boundary as well.
+   */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return (
+      value !== null &&
+      typeof value === 'object' &&
+      (value as { code?: unknown }).code === 'CTX_FETCH_HTTP_ERROR'
+    );
+  }
+
+  /** Stable machine-readable HTTP-failure code. */
+  readonly code = 'CTX_FETCH_HTTP_ERROR' as const;
+  /** Upstream HTTP status. */
+  readonly status: number;
+  /** Upstream HTTP status text. */
+  readonly statusText: string;
+  /** Final response URL after redirects. */
+  readonly url: string;
+  /** Secret-redacted response headers. */
+  readonly headers: Record<string, string>;
+  /** Complete secret-redacted response body. */
+  readonly bodyText: string;
+  /** Eagerly parsed secret-redacted JSON, or null. */
+  readonly json: unknown | null;
+
+  /** Build the error from the durable response record. */
+  constructor(readonly response: PlayAuthoringFetchResponse) {
+    const body = response.bodyText || 'empty response body';
+    super(
+      `ctx.fetch(${response.url}) returned HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}: ${body}`,
+    );
+    this.name = 'CtxFetchHttpError';
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.url = response.url;
+    this.headers = response.headers;
+    this.bodyText = response.bodyText;
+    this.json = response.json;
+  }
+}
+
 export type PlayAuthoringCustomerDbQueryOptions = {
   maxRows?: number;
   timeoutMs?: number;
@@ -1008,7 +1113,8 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<T>;
 
   /**
-   * Execute a durable, replay-safe HTTP request.
+   * Execute a guarded HTTP request. By default it is durable and replay-safe; `staleAfterSeconds` governs only that completed call receipt, never dataset/request identity. Pass `{ transient: true }` for short-lived credential exchanges or other response data that must not be retained in a receipt or checkpoint. Edition 5+ throws `CtxFetchHttpError` for non-2xx; catch it only when the Play intentionally recovers, otherwise let it fail the Play. Editions 1–4 retain their previous response projections.
+   *
    * @sdkReference runtime 170 ctx.fetch(key, url, init)
    */
   fetch(
@@ -2541,8 +2647,9 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "export type PlayCallExecution = 'inline';",
   `export type PlayCallOptions = { description: ${cloudReferenceType('ctx.runPlay.options.description')}; execution?: ${cloudReferenceType('ctx.runPlay.options.execution')}; timeoutMs?: ${cloudReferenceType('ctx.runPlay.options.timeoutMs')} };`,
   `export type RuntimeStepOptions = { semanticKey?: ${cloudReferenceType('ctx.step.semanticKey')}; staleAfterSeconds?: ${cloudReferenceType('ctx.step.staleAfterSeconds')} };`,
-  `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType('ctx.fetch.staleAfterSeconds')} };`,
+  `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType('ctx.fetch.staleAfterSeconds')}; transient?: boolean };`,
   'export type PlayFetchResponse = { ok: boolean; status: number; statusText: string; url: string; headers: Record<string, string>; bodyText: string; json: unknown | null };',
+  "export declare class CtxFetchHttpError extends Error { readonly code: 'CTX_FETCH_HTTP_ERROR'; readonly response: PlayFetchResponse; readonly status: number; readonly statusText: string; readonly url: string; readonly headers: Record<string, string>; readonly bodyText: string; readonly json: unknown | null; }",
   'export type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;',
   'export type DatasetColumnRunInput<Row, Value> = { readonly row: Row; readonly ctx: DeeplinePlayRuntimeContext; readonly index: number; readonly previousCell?: PreviousCell<Value> };',
   'export type DatasetColumnDefinition<Row, Value> = { readonly run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>; readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean> };',

package/dist/bundling-sources/shared_libs/security/safe-fetch.ts

@@ -15,6 +15,8 @@ export type SafeFetchOptions = {
   sensitiveHeaders?: Iterable<string>;
   /** Drop every caller-supplied header when a redirect changes origin. */
   stripHeadersOnCrossOriginRedirect?: boolean;
+  /** Headers the trusted runtime may add after caller headers are stripped. */
+  headersOnCrossOriginRedirect?: HeadersInit;
 };
 
 function removeHeader(headers: Headers, name: string) {
@@ -32,6 +34,7 @@ function requestInitForRedirect(
   status: number,
   sensitiveHeaders: Iterable<string>,
   stripHeadersOnCrossOriginRedirect: boolean,
+  headersOnCrossOriginRedirect: HeadersInit | undefined,
 ): RequestInit {
   let headers = new Headers(init.headers);
   let method = String(init.method ?? 'GET').toUpperCase();
@@ -57,7 +60,7 @@ function requestInitForRedirect(
       // Callers that can construct credentials from plaintext secrets cannot
       // reliably identify every transformed value. Do not forward any caller
       // header across an origin boundary in that trust model.
-      headers = new Headers();
+      headers = new Headers(headersOnCrossOriginRedirect);
     } else {
       removeHeader(headers, 'authorization');
       removeHeader(headers, 'cookie');
@@ -88,6 +91,7 @@ export async function safePublicFetch(
   const sensitiveHeaders = options.sensitiveHeaders ?? [];
   const stripHeadersOnCrossOriginRedirect =
     options.stripHeadersOnCrossOriginRedirect === true;
+  const headersOnCrossOriginRedirect = options.headersOnCrossOriginRedirect;
   let currentUrl = assertPublicHttpUrl(input);
   let currentInit: RequestInit = {
     ...init,
@@ -135,6 +139,7 @@ export async function safePublicFetch(
       response.status,
       sensitiveHeaders,
       stripHeadersOnCrossOriginRedirect,
+      headersOnCrossOriginRedirect,
     );
     currentUrl = nextUrl;
   }