tywrap 0.7.0 → 0.9.0

package/src/tywrap.ts

@@ -16,13 +16,15 @@ import type {
   Parameter,
   PythonType,
   PythonModuleConfig,
+  IrContract,
 } from './types/index.js';
 import { fsUtils, pathUtils, processUtils, isWindows } from './utils/runtime.js';
 import { globalCache } from './utils/cache.js';
 import { resolvePythonExecutable } from './utils/python.js';
 import { computeIrCacheFilename } from './utils/ir-cache.js';
+import { logger } from './utils/logger.js';
 
-const TYWRAP_IR_VERSION = '0.3.0';
+const TYWRAP_IR_VERSION = '0.4.0';
 
 // Collect unknown typing constructs encountered during annotation parsing (per-generate run)
 let unknownTypeNamesCollector: Map<string, number> = new Map();
@@ -34,7 +36,7 @@ function recordUnknown(name: string): void {
 /**
  * Main tywrap function
  */
-export interface TywrapInstance {
+interface TywrapInstance {
   mapper: TypeMapper;
   generator: CodeGenerator;
   options: Partial<TywrapOptions>;
@@ -42,7 +44,9 @@ export interface TywrapInstance {
 
 export async function tywrap(options: Partial<TywrapOptions> = {}): Promise<TywrapInstance> {
   const mapper = new TypeMapper({ presets: options.types?.presets });
-  const generator = new CodeGenerator(mapper);
+  const generator = new CodeGenerator(mapper, {
+    onTypeDegrade: typeName => recordUnknown(`unresolvable generated type ${typeName}`),
+  });
 
   globalCache.setDebug(options.debug ?? false);
 
@@ -63,7 +67,7 @@ export interface GenerateRunOptions {
 
 export interface GenerateFailure {
   module: string;
-  code: 'ir-unavailable';
+  code: 'ir-unavailable' | 'ir-version-mismatch' | 'contract-invalid';
   message: string;
 }
 
@@ -83,6 +87,68 @@ function normalizeForComparison(text: string): string {
   return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
 }
 
+function stableJson(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stableJson);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, child]) => [key, stableJson(child)])
+    );
+  }
+  return value;
+}
+
+function serializeContract(ir: IrContract): string {
+  const contract = { ...ir };
+  delete contract.metadata;
+  return `${JSON.stringify(stableJson(contract), null, 2)}\n`;
+}
+
+function validateIrVersion(
+  ir: unknown,
+  source: string
+): { ir: IrContract | null; error?: string; code?: GenerateFailure['code'] } {
+  if (ir === null || typeof ir !== 'object' || Array.isArray(ir)) {
+    return { ir: null, code: 'contract-invalid', error: `${source} is not a JSON IR object.` };
+  }
+  const contract = ir as IrContract;
+  if (typeof contract.ir_version !== 'string') {
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `${source} is missing its string ir_version.`,
+    };
+  }
+  if (contract.ir_version !== TYWRAP_IR_VERSION) {
+    return {
+      ir: null,
+      code: 'ir-version-mismatch',
+      error: `IR version mismatch: TypeScript expects ${TYWRAP_IR_VERSION}, but ${source} declares ${contract.ir_version}. Regenerate the contract with a matching tywrap_ir.`,
+    };
+  }
+  if (typeof contract.module !== 'string' || contract.module.length === 0) {
+    return { ir: null, code: 'contract-invalid', error: `${source} is missing its module name.` };
+  }
+  const requiredArrays: ReadonlyArray<readonly [string, unknown]> = [
+    ['functions', contract.functions],
+    ['classes', contract.classes],
+    ['type_aliases', contract.type_aliases],
+  ];
+  for (const [field, value] of requiredArrays) {
+    if (!Array.isArray(value)) {
+      return {
+        ir: null,
+        code: 'contract-invalid',
+        error: `${source} is missing required array field ${field}.`,
+      };
+    }
+  }
+  return { ir: contract };
+}
+
 async function safeReadFile(path: string): Promise<string | null> {
   try {
     return await fsUtils.readFile(path);
@@ -106,13 +172,17 @@ async function fetchAndCacheIr(
   cacheKey: string,
   caching: boolean,
   checkMode: boolean
-): Promise<{ ir: unknown | null; error?: string }> {
+): Promise<{ ir: IrContract | null; error?: string; code?: GenerateFailure['code'] }> {
   let ir: unknown | null = null;
   let irError: string | undefined;
   if (caching && fsUtils.isAvailable() && !checkMode) {
     try {
       const cached = await fsUtils.readFile(pathUtils.join(CACHE_DIR, cacheKey));
-      ir = JSON.parse(cached);
+      const cachedValidation = validateIrVersion(
+        JSON.parse(cached),
+        `Cached Python IR for ${moduleKey}`
+      );
+      ir = cachedValidation.ir;
     } catch {
       ir = null;
     }
@@ -124,13 +194,60 @@ async function fetchAndCacheIr(
     });
     ir = fetchResult.ir;
     irError = fetchResult.error;
-    if (ir && caching && fsUtils.isAvailable() && !checkMode) {
-      try {
-        await fsUtils.writeFile(pathUtils.join(CACHE_DIR, cacheKey), JSON.stringify(ir));
-      } catch {}
+  }
+  if (!ir) {
+    return { ir: null, error: irError, code: 'ir-unavailable' };
+  }
+  const validated = validateIrVersion(ir, `Python IR for ${moduleKey}`);
+  if (!validated.ir) {
+    return {
+      ir: null,
+      error: irError ?? validated.error,
+      code: validated.code ?? 'ir-unavailable',
+    };
+  }
+  if (caching && fsUtils.isAvailable() && !checkMode) {
+    try {
+      await fsUtils.writeFile(pathUtils.join(CACHE_DIR, cacheKey), JSON.stringify(validated.ir));
+    } catch {}
+  }
+  return { ir: validated.ir };
+}
+
+async function readContractInput(
+  moduleKey: string,
+  contractInput: TywrapOptions['contractInput']
+): Promise<{ ir: IrContract | null; error?: string; code?: GenerateFailure['code'] }> {
+  const inputPath = typeof contractInput === 'string' ? contractInput : contractInput?.[moduleKey];
+  if (!inputPath) {
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `No contractInput path configured for module ${moduleKey}.`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(await fsUtils.readFile(inputPath)) as unknown;
+    const validated = validateIrVersion(parsed, `Contract ${inputPath}`);
+    if (!validated.ir) {
+      return { ir: null, error: validated.error, code: validated.code };
     }
+    if (validated.ir.module !== moduleKey) {
+      return {
+        ir: null,
+        code: 'contract-invalid',
+        error: `Contract ${inputPath} is for module ${validated.ir.module}, not ${moduleKey}.`,
+      };
+    }
+    return { ir: validated.ir };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `Failed to read contract ${inputPath}: ${message}`,
+    };
   }
-  return { ir, error: irError };
 }
 
 /**
@@ -320,25 +437,39 @@ export async function generate(
     unknownTypeNamesCollector = new Map();
     // Resolve module IR via the Python extractor (with optional cache)
     const cacheKey = await computeCacheKey(moduleKey, resolvedOptions);
-    const { ir, error: irError } = await fetchAndCacheIr(
-      moduleKey,
-      resolvedOptions,
-      pythonPath,
-      cacheKey,
-      caching,
-      checkMode
-    );
+    const irResult = resolvedOptions.contractInput
+      ? await readContractInput(moduleKey, resolvedOptions.contractInput)
+      : await fetchAndCacheIr(moduleKey, resolvedOptions, pythonPath, cacheKey, caching, checkMode);
+    const { ir, error: irError } = irResult;
     if (!ir) {
       const message = `No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`;
       warnings.push(message);
       failures.push({
         module: moduleKey,
-        code: 'ir-unavailable',
+        code: irResult.code ?? 'ir-unavailable',
         message,
       });
       continue;
     }
 
+    const irWarnings = Array.isArray((ir as Record<string, unknown>).warnings)
+      ? ((ir as Record<string, unknown>).warnings as unknown[])
+      : [];
+    for (const warning of irWarnings) {
+      if (typeof warning !== 'string') {
+        continue;
+      }
+      // Only type-honesty degrades feed --fail-on-warn. Environment capability
+      // notices (e.g. typing.get_overloads missing on Python < 3.11) describe
+      // the analyzing interpreter, not the generated types, and must not fail
+      // an otherwise clean build.
+      if (warning.startsWith('Return annotation for ')) {
+        recordUnknown(`Python IR warning: ${warning}`);
+      } else {
+        logger.info(`Python IR notice: ${warning}`, { component: 'Generate' });
+      }
+    }
+
     const moduleModel = transformIrToTsModel(ir);
 
     // Apply module-level export filtering (functions/classes + excludes).
@@ -351,6 +482,10 @@ export async function generate(
     const baseName = moduleModel.name || 'module';
     const filesToEmit: Array<{ path: string; content: string }> = [
       { path: pathUtils.join(outputDir, `${baseName}.generated.ts`), content: gen.typescript },
+      {
+        path: pathUtils.join(outputDir, `${baseName}.contract.json`),
+        content: serializeContract(ir),
+      },
     ];
 
     // Optional .d.ts emission (header-only declarations mirroring exports)
@@ -441,15 +576,7 @@ async function fetchPythonIr(
   try {
     const primary = await execAndParseIr(
       pythonPath,
-      [
-        '-m',
-        'tywrap_ir',
-        '--module',
-        moduleName,
-        '--ir-version',
-        TYWRAP_IR_VERSION,
-        '--no-pretty',
-      ],
+      ['-m', 'tywrap_ir', '--module', moduleName, '--no-pretty'],
       execOptions,
       'tywrap_ir output'
     );
@@ -484,7 +611,7 @@ async function fetchPythonIr(
 
     const fallback = await execAndParseIr(
       pythonPath,
-      [localMain, '--module', moduleName, '--ir-version', TYWRAP_IR_VERSION, '--no-pretty'],
+      [localMain, '--module', moduleName, '--no-pretty'],
       execOptions,
       'tywrap_ir fallback output'
     );

package/src/utils/cache.ts

@@ -12,7 +12,7 @@ import { getComponentLogger } from './logger.js';
 
 const log = getComponentLogger('Cache');
 
-export interface CacheEntry<T = unknown> {
+interface CacheEntry<T = unknown> {
   key: string;
   data: T;
   timestamp: number;
@@ -27,7 +27,7 @@ export interface CacheEntry<T = unknown> {
   };
 }
 
-export interface CacheStats {
+interface CacheStats {
   totalEntries: number;
   totalSize: number;
   hitRate: number;
@@ -36,7 +36,7 @@ export interface CacheStats {
   memoryUsage: number;
 }
 
-export interface CacheConfig {
+interface CacheConfig {
   baseDir: string;
   maxSize: number; // Maximum cache size in bytes
   maxAge: number; // Maximum age in milliseconds

package/src/utils/codec.ts

@@ -9,6 +9,8 @@
  * Sklearn estimators: { "__tywrap__": "sklearn.estimator", "encoding": "json", ... }
  */
 
+import { tagDecodedShape } from '../runtime/validators.js';
+
 // Avoid hard dependency on apache-arrow types at compile time to keep install optional.
 export type ArrowTable = { readonly numCols?: number; readonly numRows?: number } & Record<
   string,
@@ -68,6 +70,7 @@ export type ValueEnvelope =
       readonly b64?: string; // when encoding=arrow
       readonly data?: unknown; // when encoding=json
       readonly shape?: readonly number[];
+      readonly dtype?: string | null;
     }
   | {
       readonly __tywrap__: 'scipy.sparse';
@@ -442,13 +445,16 @@ function decodeArrowOrJsonEnvelope<T>(
       throw new Error(`Invalid ${typeTag} envelope: missing b64`);
     }
     const bytes = fromBase64(b64);
-    return decodeArrow(bytes);
+    const decoded = decodeArrow(bytes);
+    return isPromiseLike(decoded)
+      ? decoded.then(item => tagDecodedShape(item, { marker: typeTag as 'dataframe' | 'series' }))
+      : tagDecodedShape(decoded, { marker: typeTag as 'dataframe' | 'series' });
   }
   if (encoding === 'json') {
     if (!('data' in value)) {
       throw new Error(`Invalid ${typeTag} envelope: missing data`);
     }
-    return value.data;
+    return tagDecodedShape(value.data, { marker: typeTag as 'dataframe' | 'series' });
   }
   throw new Error(`Invalid ${typeTag} envelope: unsupported encoding ${String(encoding)}`);
 }
@@ -463,6 +469,8 @@ const decodeNdarrayEnvelope: EnvelopeHandler = (value, decodeArrow) => {
   const encoding = value.encoding;
   const shapeValue = value.shape;
   const shape = isNumberArray(shapeValue) ? shapeValue : undefined;
+  const dtype = typeof value.dtype === 'string' ? value.dtype : undefined;
+  const metadata = { marker: 'ndarray' as const, dims: shape?.length, dtype };
 
   if (encoding === 'arrow') {
     const b64 = value.b64;
@@ -480,34 +488,59 @@ const decodeNdarrayEnvelope: EnvelopeHandler = (value, decodeArrow) => {
       return decoded.then(data => {
         const values = extractArrowValues(data);
         if (!values) {
-          return data; // Fallback: return raw data if extraction fails
+          return tagDecodedShape(data, metadata); // Fallback: keep provenance on raw data.
         }
         // Reshape scalars and multi-dimensional arrays, but not 1D
-        if (shape && shape.length !== 1) {
-          return reshapeArray(values, shape);
-        }
-        return values;
+        return tagDecodedShape(
+          shape && shape.length !== 1 ? reshapeArray(values, shape) : values,
+          metadata
+        );
       });
     }
     const values = extractArrowValues(decoded);
     if (!values) {
-      return decoded; // Fallback: return raw data if extraction fails
+      return tagDecodedShape(decoded, metadata); // Fallback: keep provenance on raw data.
     }
     // Reshape scalars and multi-dimensional arrays, but not 1D
-    if (shape && shape.length !== 1) {
-      return reshapeArray(values, shape);
-    }
-    return values;
+    return tagDecodedShape(
+      shape && shape.length !== 1 ? reshapeArray(values, shape) : values,
+      metadata
+    );
   }
   if (encoding === 'json') {
     if (!('data' in value)) {
       throw new Error('Invalid ndarray envelope: missing data');
     }
-    return value.data;
+    return tagDecodedShape(value.data, metadata);
   }
   throw new Error(`Invalid ndarray envelope: unsupported encoding ${String(encoding)}`);
 };
 
+/**
+ * Assert an array holds only integer indices within [0, bound). Used to re-validate
+ * scipy.sparse index arrays on the JS side so a corrupt/oversized index can never
+ * silently address out of the declared shape.
+ *
+ * Why: the JS decoder never reconstructs a Python object, but it IS the boundary a
+ * downstream consumer trusts — validating index ranges here turns a corrupt payload
+ * into a clear, early failure instead of a confusing downstream error.
+ */
+function assertIndexArrayInRange(arr: readonly unknown[], bound: number, label: string): void {
+  for (let i = 0; i < arr.length; i += 1) {
+    const idx = arr[i];
+    if (typeof idx !== 'number' || !Number.isInteger(idx)) {
+      throw new Error(
+        `Invalid scipy.sparse envelope: ${label}[${i}] must be an integer, got ${String(idx)}`
+      );
+    }
+    if (idx < 0 || idx >= bound) {
+      throw new Error(
+        `Invalid scipy.sparse envelope: ${label}[${i}]=${idx} is out of range [0, ${bound})`
+      );
+    }
+  }
+}
+
 const decodeScipySparseEnvelope: EnvelopeHandler = value => {
   const encoding = value.encoding;
   if (encoding !== 'json') {
@@ -522,10 +555,16 @@ const decodeScipySparseEnvelope: EnvelopeHandler = value => {
     !Array.isArray(shape) ||
     shape.length !== 2 ||
     typeof shape[0] !== 'number' ||
-    typeof shape[1] !== 'number'
+    !Number.isInteger(shape[0]) ||
+    shape[0] < 0 ||
+    typeof shape[1] !== 'number' ||
+    !Number.isInteger(shape[1]) ||
+    shape[1] < 0
   ) {
-    throw new Error('Invalid scipy.sparse envelope: shape must be a 2-item number[]');
+    throw new Error('Invalid scipy.sparse envelope: shape must be a 2-item non-negative integer[]');
   }
+  const rows = shape[0];
+  const cols = shape[1];
   const data = value.data;
   if (!Array.isArray(data)) {
     throw new Error('Invalid scipy.sparse envelope: data must be an array');
@@ -539,6 +578,16 @@ const decodeScipySparseEnvelope: EnvelopeHandler = value => {
     if (!Array.isArray(row) || !Array.isArray(col)) {
       throw new Error('Invalid scipy.sparse envelope: coo requires row and col arrays');
     }
+    // COO: one (row, col, value) triple per stored entry, so all three arrays
+    // share a length; row/col index into [0, rows)/[0, cols) respectively.
+    if (row.length !== data.length || col.length !== data.length) {
+      throw new Error(
+        `Invalid scipy.sparse envelope: coo row/col/data lengths must match ` +
+          `(data=${data.length}, row=${row.length}, col=${col.length})`
+      );
+    }
+    assertIndexArrayInRange(row, rows, 'row');
+    assertIndexArrayInRange(col, cols, 'col');
     return {
       format,
       shape,
@@ -554,6 +603,52 @@ const decodeScipySparseEnvelope: EnvelopeHandler = value => {
   if (!Array.isArray(indices) || !Array.isArray(indptr)) {
     throw new Error('Invalid scipy.sparse envelope: csr/csc requires indices and indptr arrays');
   }
+  // CSR/CSC: one column-index (CSR) or row-index (CSC) per stored value, so
+  // indices and data share a length. indptr partitions indices into one segment
+  // per major axis (rows for CSR, cols for CSC), so indptr has majorAxis + 1
+  // entries; the inner indices address the minor axis.
+  if (indices.length !== data.length) {
+    throw new Error(
+      `Invalid scipy.sparse envelope: ${format} indices/data lengths must match ` +
+        `(data=${data.length}, indices=${indices.length})`
+    );
+  }
+  const majorAxis = format === 'csr' ? rows : cols;
+  const minorAxis = format === 'csr' ? cols : rows;
+  if (indptr.length !== majorAxis + 1) {
+    throw new Error(
+      `Invalid scipy.sparse envelope: ${format} indptr length must be ${majorAxis + 1} ` +
+        `(${format === 'csr' ? 'rows' : 'cols'}+1), got ${indptr.length}`
+    );
+  }
+  // indptr must be a valid CSR/CSC pointer array: integers that start at 0, end
+  // at data.length, and never decrease — otherwise a structurally impossible
+  // matrix (e.g. [0, 99, 1]) would slip through the length check above.
+  for (let i = 0; i < indptr.length; i += 1) {
+    const ptr = indptr[i];
+    if (typeof ptr !== 'number' || !Number.isInteger(ptr)) {
+      throw new Error(
+        `Invalid scipy.sparse envelope: indptr[${i}] must be an integer, got ${String(ptr)}`
+      );
+    }
+    if (ptr < 0 || ptr > data.length) {
+      throw new Error(
+        `Invalid scipy.sparse envelope: indptr[${i}]=${ptr} is out of range [0, ${data.length}]`
+      );
+    }
+    if (i > 0 && ptr < (indptr[i - 1] as number)) {
+      throw new Error('Invalid scipy.sparse envelope: indptr must be non-decreasing');
+    }
+  }
+  if (indptr[0] !== 0) {
+    throw new Error('Invalid scipy.sparse envelope: indptr must start at 0');
+  }
+  if (indptr[indptr.length - 1] !== data.length) {
+    throw new Error(
+      `Invalid scipy.sparse envelope: indptr must end at data.length (${data.length})`
+    );
+  }
+  assertIndexArrayInRange(indices, minorAxis, 'indices');
   return {
     format,
     shape,
@@ -564,6 +659,11 @@ const decodeScipySparseEnvelope: EnvelopeHandler = value => {
   } satisfies SparseMatrix;
 };
 
+/** Product of a shape's dimensions (the element count). [] (scalar) -> 1. */
+function shapeProduct(shape: readonly number[]): number {
+  return shape.reduce((acc, dim) => acc * dim, 1);
+}
+
 const decodeTorchTensorEnvelope: EnvelopeHandler = <T>(
   value: { [k: string]: unknown },
   _decodeArrow: (bytes: Uint8Array) => MaybePromise<T>,
@@ -580,20 +680,96 @@ const decodeTorchTensorEnvelope: EnvelopeHandler = <T>(
   if (!isObject(nested) || (nested as { __tywrap__?: unknown }).__tywrap__ !== 'ndarray') {
     throw new Error('Invalid torch.tensor envelope: value must be an ndarray envelope');
   }
-  const decoded = recurse(nested);
   const shapeValue = value.shape;
   const shape = isNumberArray(shapeValue) ? shapeValue : undefined;
+  // The tensor shape must be a non-negative-integer dimension list. A negative or
+  // non-integer dim is a corrupt envelope, not a valid tensor.
+  if (shape) {
+    for (let i = 0; i < shape.length; i += 1) {
+      const dim = shape[i] as number;
+      if (!Number.isInteger(dim) || dim < 0) {
+        throw new Error(
+          `Invalid torch.tensor envelope: shape[${i}]=${dim} must be a non-negative integer`
+        );
+      }
+    }
+  }
+  // Cross-check the tensor shape's element count against the nested ndarray's
+  // declared shape (metadata only — no decode needed). A mismatch means the two
+  // shapes disagree about how many elements the payload holds.
+  const nestedShapeValue = (nested as { shape?: unknown }).shape;
+  const nestedShape = isNumberArray(nestedShapeValue) ? nestedShapeValue : undefined;
+  if (shape && nestedShape && shapeProduct(shape) !== shapeProduct(nestedShape)) {
+    throw new Error(
+      `Invalid torch.tensor envelope: shape ${JSON.stringify(shape)} ` +
+        `(product ${shapeProduct(shape)}) disagrees with nested ndarray shape ` +
+        `${JSON.stringify(nestedShape)} (product ${shapeProduct(nestedShape)})`
+    );
+  }
   const dtypeValue = value.dtype;
   const dtype = typeof dtypeValue === 'string' ? dtypeValue : undefined;
   const deviceValue = value.device;
+  if (deviceValue !== undefined && (typeof deviceValue !== 'string' || deviceValue.length === 0)) {
+    throw new Error(
+      'Invalid torch.tensor envelope: device must be a non-empty string when provided'
+    );
+  }
   const device = typeof deviceValue === 'string' ? deviceValue : undefined;
 
+  const decoded = recurse(nested);
   if (isPromiseLike(decoded)) {
     return decoded.then(data => ({ data, shape, dtype, device })) as Promise<T | unknown>;
   }
   return { data: decoded, shape, dtype, device } satisfies TorchTensor;
 };
 
+/**
+ * Recursively assert a value is plain JSON (null | boolean | number | string |
+ * JSON array | plain object of JSON). Rejects functions, symbols, bigints, class
+ * instances, and any non-finite number — the things a metadata-only sklearn
+ * envelope must never carry. This validates; it never reconstructs.
+ */
+function assertPlainJson(value: unknown, path: string): void {
+  if (value === null) {
+    return;
+  }
+  const t = typeof value;
+  if (t === 'string' || t === 'boolean') {
+    return;
+  }
+  if (t === 'number') {
+    if (!Number.isFinite(value as number)) {
+      throw new Error(
+        `Invalid sklearn.estimator envelope: ${path} must be a finite JSON number, got ${String(value)}`
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertPlainJson(item, `${path}[${i}]`));
+    return;
+  }
+  if (t === 'object') {
+    // Reject exotic objects (class instances, Map/Set, etc.): a JSON object is a
+    // plain object whose prototype is Object.prototype or null.
+    const proto = Object.getPrototypeOf(value as object);
+    if (proto !== Object.prototype && proto !== null) {
+      throw new Error(
+        `Invalid sklearn.estimator envelope: ${path} must be a plain JSON object, ` +
+          `got ${(value as object).constructor?.name ?? 'object'}`
+      );
+    }
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      assertPlainJson(v, `${path}.${k}`);
+    }
+    return;
+  }
+  // function | symbol | bigint | undefined
+  throw new Error(
+    `Invalid sklearn.estimator envelope: ${path} is not JSON-serializable (type ${t})`
+  );
+}
+
 const decodeSklearnEstimatorEnvelope: EnvelopeHandler = value => {
   const encoding = value.encoding;
   if (encoding !== 'json') {
@@ -607,6 +783,19 @@ const decodeSklearnEstimatorEnvelope: EnvelopeHandler = value => {
       'Invalid sklearn.estimator envelope: expected className/module strings + params object'
     );
   }
+  // params must be a PLAIN JSON object end to end — metadata-only estimators never
+  // carry callables, class instances, or nested non-JSON values. Validate (do not
+  // reconstruct) so a corrupt envelope fails clearly instead of leaking a function
+  // or exotic object to a downstream consumer.
+  if (
+    Object.getPrototypeOf(params) !== Object.prototype &&
+    Object.getPrototypeOf(params) !== null
+  ) {
+    throw new Error('Invalid sklearn.estimator envelope: params must be a plain JSON object');
+  }
+  for (const [k, v] of Object.entries(params)) {
+    assertPlainJson(v, `params.${k}`);
+  }
   const versionValue = value.version;
   if (versionValue !== undefined && typeof versionValue !== 'string') {
     throw new Error('Invalid sklearn.estimator envelope: version must be a string when provided');

package/src/utils/ir-cache.ts

@@ -1,6 +1,6 @@
 import { hashUtils } from './runtime.js';
 
-export interface IrCacheKeyObject {
+interface IrCacheKeyObject {
   module: string;
   moduleVersion: string | null;
   irVersion: string;