deepline 0.3.90 → 0.3.91

package/dist/bundling-sources/shared_libs/plays/launch/input-contract.ts

@@ -0,0 +1,400 @@
+/**
+ * Server-side enforcement of the play input contract at run creation.
+ *
+ * Two distinct guards, both intended to run BEFORE any run/billing artifact is
+ * created (see `apps/deepline-api/src/app/api/v2/plays/run/route.ts` `startPlayRunForAuth`):
+ *
+ * 1. `validateScalarInputAgainstSchema` — validates the scalar `--input`
+ *    envelope against the play's declared `inputSchema`. Enforces
+ *    `additionalProperties: false` (unknown keys are rejected), the declared
+ *    JSON-schema `type` of each declared property, declared string
+ *    `minLength`/`maxLength` (so `csv: ""` against `minLength:1` is a 400 rather
+ *    than a paid failed run), and CSV-vs-scalar mutual exclusion (a non-empty
+ *    `csv` path may not coexist with scalar data fields). This is a HARD
+ *    CUTOVER: no warn phase, env flag, or compatibility shim. Previously nothing
+ *    validated scalar input server-side, so `--input '{"foo":"bar"}'` against a
+ *    play with `additionalProperties: false` silently exported `foo`, and a
+ *    `csv` alongside scalar fields silently dropped the scalars.
+ *
+ *    SCOPE: scalar envelope keys ONLY. CSV column passthrough is BY DESIGN
+ *    (source-column preservation). CSV columns never appear in the scalar input
+ *    object — the scalar envelope for a CSV play declares `csv` (a string path)
+ *    and `columns` (an alias map), while real CSV header names live at the row
+ *    level (`csvInput.rowInputSchema`, `additionalProperties: true`). Validating
+ *    the scalar envelope therefore never touches CSV column names.
+ *
+ * 2. `assertCsvHasDataRows` — rejects a CSV that has a header row but zero data
+ *    rows, before the run is created/charged. A header-only CSV otherwise
+ *    creates a paid failed run (~$0.02).
+ *
+ * Both helpers return a structured failure compatible with the run route's
+ * `PlayRunStartFailure` envelope (`{ status, error, details? }`) instead of
+ * throwing, so the route can surface a clean 400 to the client.
+ */
+
+export type PlayInputContractFailure = {
+  status: 400;
+  error: string;
+  details?: Record<string, unknown>;
+};
+
+type DeclaredInputSchema = {
+  type?: unknown;
+  additionalProperties?: unknown;
+  properties?: unknown;
+  required?: unknown;
+  /**
+   * Prebuilt CSV plays carry a top-level `csvInput` descriptor. We read
+   * `csvInput.inputField` to learn which declared property is the CSV path
+   * (defaults to `"csv"`), so the csv-vs-scalar mutual-exclusion check is driven
+   * by the schema rather than a hardcoded key name.
+   */
+  csvInput?: unknown;
+};
+
+/**
+ * Declared property names that are CSV-control inputs (not row data): the alias
+ * map that remaps source CSV headers onto canonical play fields. These may
+ * coexist with the CSV path. Derived structurally below; this constant just
+ * names the well-known control key in the prebuilt schema shape.
+ */
+const CSV_CONTROL_KEYS = new Set<string>(['columns']);
+
+function csvControlKeys(schema: Record<string, unknown>): Set<string> {
+  const keys = new Set(CSV_CONTROL_KEYS);
+  const csvInput = schema.csvInput;
+  if (!isPlainObject(csvInput)) return keys;
+  const runLevelControls = csvInput.runLevelControlFields;
+  if (!Array.isArray(runLevelControls)) return keys;
+  for (const field of runLevelControls) {
+    if (typeof field === 'string' && field.trim()) {
+      keys.add(field.trim());
+    }
+  }
+  return keys;
+}
+
+/**
+ * Resolve which declared scalar property is the CSV-path input for this schema.
+ * Driven by `csvInput.inputField`; absent that descriptor the schema is not a
+ * CSV play and there is no csv key.
+ */
+function csvInputFieldName(schema: Record<string, unknown>): string | null {
+  const csvInput = schema.csvInput;
+  if (!isPlainObject(csvInput)) return null;
+  const field = csvInput.inputField;
+  return typeof field === 'string' && field.length > 0 ? field : 'csv';
+}
+
+/**
+ * The JSON-schema `type` keyword we know how to check at the scalar envelope
+ * level. Anything outside this set (e.g. union schemas via `anyOf`) is left
+ * un-type-checked here; presence/`additionalProperties` is still enforced.
+ */
+type SimpleJsonType =
+  | 'object'
+  | 'array'
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'null';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function jsonTypeOf(value: unknown): SimpleJsonType {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  const t = typeof value;
+  if (t === 'object') return 'object';
+  if (t === 'string') return 'string';
+  if (t === 'boolean') return 'boolean';
+  if (t === 'number') {
+    return Number.isInteger(value as number) ? 'integer' : 'number';
+  }
+  // Functions / undefined / symbol cannot appear in parsed JSON input.
+  return 'object';
+}
+
+function typeMatches(
+  received: SimpleJsonType,
+  expected: SimpleJsonType,
+): boolean {
+  if (received === expected) return true;
+  // A JSON `integer` value satisfies a declared `number`.
+  if (expected === 'number' && received === 'integer') return true;
+  // A whole-valued `number` satisfies a declared `integer`.
+  if (expected === 'integer' && received === 'number') return true;
+  return false;
+}
+
+function declaredTypeFor(propertySchema: unknown): SimpleJsonType | null {
+  if (!isPlainObject(propertySchema)) return null;
+  const declared = propertySchema.type;
+  if (typeof declared !== 'string') return null;
+  switch (declared) {
+    case 'object':
+    case 'array':
+    case 'string':
+    case 'number':
+    case 'integer':
+    case 'boolean':
+    case 'null':
+      return declared;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Validate the scalar `--input` envelope against the play's declared
+ * `inputSchema`. Returns `null` when the input is acceptable, otherwise a 400
+ * failure describing the first violation class encountered (unknown keys, then
+ * type mismatches).
+ *
+ * When `schema` is null/absent, or does not declare `additionalProperties:
+ * false` and has no checkable property types, this is a no-op (returns null) —
+ * plays without a strict schema are unaffected, per the task contract.
+ */
+export function validateScalarInputAgainstSchema(input: {
+  scalarInput: Record<string, unknown>;
+  schema: DeclaredInputSchema | null | undefined;
+  playName?: string | null;
+}): PlayInputContractFailure | null {
+  const { scalarInput, schema } = input;
+  if (!isPlainObject(schema)) return null;
+
+  const properties = isPlainObject(schema.properties) ? schema.properties : {};
+  const allowedKeys = Object.keys(properties);
+  const additionalPropsForbidden = schema.additionalProperties === false;
+
+  const inputKeys = Object.keys(scalarInput);
+
+  // 1. additionalProperties: false → reject unknown scalar keys.
+  if (additionalPropsForbidden) {
+    const unknownKeys = inputKeys.filter((key) => !(key in properties));
+    if (unknownKeys.length > 0) {
+      const playLabel = input.playName ? ` for play "${input.playName}"` : '';
+      return {
+        status: 400,
+        error: `Unknown input ${
+          unknownKeys.length === 1 ? 'key' : 'keys'
+        }${playLabel}: ${unknownKeys
+          .map((key) => `"${key}"`)
+          .join(', ')}. Allowed ${
+          allowedKeys.length === 1 ? 'key is' : 'keys are'
+        }: ${
+          allowedKeys.length > 0
+            ? allowedKeys.map((key) => `"${key}"`).join(', ')
+            : '(none)'
+        }.`,
+        details: {
+          unknownKeys,
+          allowedKeys,
+        },
+      };
+    }
+  }
+
+  // 2. CSV-vs-scalar mutual exclusion. For a CSV-backed play, the scalar
+  //    envelope either supplies a CSV path (`csv`) OR per-row scalar data fields
+  //    — never both. Production run 20260611t145724-650 sent a non-empty `csv`
+  //    AND scalar data fields (linkedin_url, current_domain, contact_full_name)
+  //    and the run silently used only the CSV. The csv key and the control keys
+  //    (e.g. `columns`, the header-alias map) may coexist; any OTHER declared
+  //    property supplied alongside a non-empty csv is a conflicting data field.
+  const csvKey = csvInputFieldName(schema);
+  if (csvKey && csvKey in properties) {
+    const csvControls = csvControlKeys(schema);
+    const csvValue = scalarInput[csvKey];
+    const csvSupplied =
+      typeof csvValue === 'string'
+        ? csvValue.length > 0
+        : csvValue !== undefined && csvValue !== null;
+    if (csvSupplied) {
+      const conflictingKeys = inputKeys.filter(
+        (key) =>
+          key !== csvKey &&
+          !csvControls.has(key) &&
+          key in properties &&
+          scalarInput[key] !== undefined,
+      );
+      if (conflictingKeys.length > 0) {
+        const playLabel = input.playName ? ` for play "${input.playName}"` : '';
+        return {
+          status: 400,
+          error: `Conflicting input${playLabel}: "${csvKey}" and scalar data ${
+            conflictingKeys.length === 1 ? 'field' : 'fields'
+          } ${conflictingKeys
+            .map((key) => `"${key}"`)
+            .join(
+              ', ',
+            )} are mutually exclusive. Put the values in the CSV or remove "${csvKey}".`,
+          details: {
+            csvKey,
+            conflictingKeys,
+          },
+        };
+      }
+    }
+  }
+
+  // 3. Type mismatches and string-length constraints on declared properties
+  //    (e.g. custom_fields: string when the schema declares object; an empty
+  //    `csv: ""` against a declared minLength:1). Only checks keys the caller
+  //    actually supplied; required-field enforcement is left to downstream
+  //    runtime validation (the play's own input contract), matching prior
+  //    behavior.
+  for (const key of inputKeys) {
+    if (!(key in properties)) continue; // unknown keys handled above
+    const propertySchema = properties[key];
+    const expected = declaredTypeFor(propertySchema);
+    const value = scalarInput[key];
+    // Optional fields explicitly set to null/undefined are not checked here;
+    // absence is handled by required-field validation downstream.
+    if (value === undefined) continue;
+
+    if (expected) {
+      const received = jsonTypeOf(value);
+      if (!typeMatches(received, expected)) {
+        const playLabel = input.playName ? ` for play "${input.playName}"` : '';
+        return {
+          status: 400,
+          error: `Invalid type for input field "${key}"${playLabel}: expected ${expected}, received ${received}.`,
+          details: {
+            field: key,
+            expectedType: expected,
+            receivedType: received,
+          },
+        };
+      }
+    }
+
+    // String-length constraints. Generalized from the schema — production run
+    // 20260611t150001-525 passed `csv: ""` against a declared minLength:1 and
+    // created a paid failed run ("no asset binding"). Enforced for any declared
+    // string property carrying minLength/maxLength.
+    if (typeof value === 'string' && isPlainObject(propertySchema)) {
+      const lengthFailure = checkStringLength({
+        key,
+        value,
+        propertySchema,
+        playName: input.playName ?? null,
+      });
+      if (lengthFailure) return lengthFailure;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Enforce declared `minLength` / `maxLength` for a supplied string value.
+ * Returns a 400 failure naming the field and the violated constraint, otherwise
+ * null. Only fires when the property schema declares the bound as a number.
+ */
+function checkStringLength(input: {
+  key: string;
+  value: string;
+  propertySchema: Record<string, unknown>;
+  playName: string | null;
+}): PlayInputContractFailure | null {
+  const { key, value, propertySchema, playName } = input;
+  const playLabel = playName ? ` for play "${playName}"` : '';
+
+  const minLength = propertySchema.minLength;
+  if (typeof minLength === 'number' && value.length < minLength) {
+    return {
+      status: 400,
+      error:
+        minLength === 1
+          ? `${key} must be a non-empty string (minLength 1)${playLabel}.`
+          : `${key} must be at least ${minLength} characters (minLength ${minLength})${playLabel}; received length ${value.length}.`,
+      details: {
+        field: key,
+        constraint: 'minLength',
+        minLength,
+        receivedLength: value.length,
+      },
+    };
+  }
+
+  const maxLength = propertySchema.maxLength;
+  if (typeof maxLength === 'number' && value.length > maxLength) {
+    return {
+      status: 400,
+      error: `${key} must be at most ${maxLength} characters (maxLength ${maxLength})${playLabel}; received length ${value.length}.`,
+      details: {
+        field: key,
+        constraint: 'maxLength',
+        maxLength,
+        receivedLength: value.length,
+      },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Inspect raw CSV bytes and reject a CSV that has a header row but zero data
+ * rows. Returns null when the CSV has at least one data row (or when the bytes
+ * are not parseable as a header-bearing CSV — that is left to the runtime CSV
+ * parser to surface, so this guard is strictly additive and never masks other
+ * failures).
+ *
+ * "Data row" = any non-empty line after the first (header) line. Trailing
+ * blank lines and a trailing newline after the header are ignored.
+ */
+export function assertCsvHasDataRows(input: {
+  csvText: string;
+  logicalPath?: string | null;
+}): PlayInputContractFailure | null {
+  const { csvText } = input;
+  if (typeof csvText !== 'string') return null;
+
+  // Normalize line endings, then split. A header-only file is one where every
+  // line after the first is empty (or there is only a header line).
+  const lines = csvText.replace(/\r\n?/g, '\n').split('\n');
+  if (lines.length === 0) return null;
+
+  // No header at all (empty file) — leave to the runtime parser; not our guard.
+  const header = lines[0];
+  if (!header || header.trim().length === 0) return null;
+
+  const hasDataRow = lines.slice(1).some((line) => line.trim().length > 0);
+
+  if (hasDataRow) return null;
+
+  const pathLabel = input.logicalPath ? ` ("${input.logicalPath}")` : '';
+  return {
+    status: 400,
+    error: `csv has a header row but no data rows${pathLabel}.`,
+    details: {
+      ...(input.logicalPath ? { logicalPath: input.logicalPath } : {}),
+      reason: 'csv_header_only',
+    },
+  };
+}
+
+/**
+ * Decode a base64-encoded CSV upload to text for the zero-row backstop. Returns
+ * null when the content type is not CSV or the payload cannot be decoded
+ * (decoding failure is surfaced by the runtime, not masked here).
+ */
+export function decodeCsvUploadText(input: {
+  contentType: string;
+  contentBase64: string;
+}): string | null {
+  const contentType = input.contentType.toLowerCase();
+  const isCsv =
+    contentType.includes('text/csv') || contentType.includes('application/csv');
+  if (!isCsv) return null;
+  try {
+    return Buffer.from(input.contentBase64, 'base64').toString('utf-8');
+  } catch {
+    return null;
+  }
+}

package/dist/bundling-sources/shared_libs/plays/launch/prepare.ts

@@ -0,0 +1,96 @@
+import type { PlayBundleArtifact } from '../artifact-types';
+import {
+  normalizePlayContractCompatibility,
+  type NormalizedPlayContractCompatibilitySnapshot,
+  type PlayRunContractSnapshot,
+} from '../contracts';
+import { stripInlineSourceMapFromArtifact } from '../artifact-transport';
+import type { PlaySandboxRuntimeLimits } from '../sandbox-runtime-limits';
+import type { AdmittedPlayAuthoringContract } from '../authoring-contract';
+
+const MAX_INLINE_PLAY_ARTIFACT_BYTES = 1_500_000;
+
+export type PlayRunLaunchValidationSnapshot = {
+  sourceCode: string;
+  staticPipeline: unknown;
+  artifactHash: string;
+  graphHash: string;
+  maxCreditsPerRun: number | null;
+  sandboxRuntimeLimits: PlaySandboxRuntimeLimits;
+  authoringContract: AdmittedPlayAuthoringContract;
+};
+
+export type PreparedPlayRunContractSnapshot = PlayRunContractSnapshot & {
+  compatibility: NormalizedPlayContractCompatibilitySnapshot;
+};
+
+export function runtimeArtifactForSchedulerInput(
+  artifact: PlayBundleArtifact | null | undefined,
+): PlayBundleArtifact | null {
+  if (!artifact) {
+    return null;
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(artifact), 'utf-8');
+  if (bytes > MAX_INLINE_PLAY_ARTIFACT_BYTES) {
+    console.info('[perf][plays.start_run]', {
+      phase: 'runtime_artifact_inline_skipped',
+      ms: 0,
+      artifactBytes: bytes,
+      maxBytes: MAX_INLINE_PLAY_ARTIFACT_BYTES,
+    });
+    return null;
+  }
+  // The scheduler prefers this inline artifact to the stored copy. Keep its
+  // map so a Daytona runner can map user errors without an extra artifact read;
+  // the size gate above already accounts for the complete artifact.
+  const compacted = stripInlineSourceMapFromArtifact(artifact);
+  console.info('[perf][plays.start_run]', {
+    phase: 'runtime_artifact_inline_compacted',
+    ms: 0,
+    originalArtifactBytes: bytes,
+    compactedArtifactBytes: Buffer.byteLength(
+      JSON.stringify(compacted),
+      'utf-8',
+    ),
+  });
+  return compacted;
+}
+
+export function buildPlayRunContractSnapshot(input: {
+  source?: 'published' | 'ad_hoc' | 'draft';
+  artifactStorageKey: string;
+  artifact: Pick<PlayBundleArtifact, 'compatibility'>;
+  validatedSnapshot: PlayRunLaunchValidationSnapshot;
+  transportStaticPipeline?: unknown;
+}): PreparedPlayRunContractSnapshot {
+  // The runtime backend is launch infrastructure, not an artifact contract.
+  // Copy the admitted artifact compatibility so resumed work cannot acquire
+  // newer semantics merely because the runtime was redeployed.
+  const compatibility = normalizePlayContractCompatibility(
+    input.artifact.compatibility,
+  );
+  const staticPipeline =
+    input.transportStaticPipeline ?? input.validatedSnapshot.staticPipeline;
+  return {
+    source: input.source ?? 'published',
+    revisionVersion: null,
+    staticPipeline,
+    billingLimit:
+      typeof input.validatedSnapshot.maxCreditsPerRun === 'number'
+        ? { maxCreditsPerRun: input.validatedSnapshot.maxCreditsPerRun }
+        : null,
+    runtimeLimit: input.validatedSnapshot.sandboxRuntimeLimits,
+    sourceCode: input.validatedSnapshot.sourceCode,
+    artifactMetadata: {
+      storageKey: input.artifactStorageKey,
+      artifactHash: input.validatedSnapshot.artifactHash,
+      graphHash: input.validatedSnapshot.graphHash,
+    },
+    codeFormat: 'cjs_module',
+    compatibility,
+    authoringContract: {
+      ...input.validatedSnapshot.authoringContract,
+      staticPipeline,
+    },
+  };
+}