tywrap 0.9.0 → 0.10.0

package/dist/utils/codec.js

@@ -9,6 +9,34 @@
  * Sklearn estimators: { "__tywrap__": "sklearn.estimator", "encoding": "json", ... }
  */
 import { tagDecodedShape } from '../runtime/validators.js';
+const SCIENTIFIC_MARKERS = [
+    'dataframe',
+    'series',
+    'ndarray',
+    'scipy.sparse',
+    'torch.tensor',
+    'sklearn.estimator',
+];
+export function isScientificMarker(value) {
+    return SCIENTIFIC_MARKERS.includes(value);
+}
+/** @internal Structured failure consumed by BridgeCodec without parsing messages. */
+export class ScientificDecodeError extends Error {
+    kind;
+    marker;
+    cause;
+    constructor(kind, marker, cause, message = cause instanceof Error ? cause.message : String(cause)) {
+        super(message, { cause });
+        this.kind = kind;
+        this.marker = marker;
+        this.cause = cause;
+    }
+}
+function asScientificDecodeError(error, marker) {
+    return error instanceof ScientificDecodeError
+        ? error
+        : new ScientificDecodeError('envelope', marker, error);
+}
 let arrowTableFrom;
 // Why: lazy auto-registration (on first Arrow decode) imports apache-arrow at most
 // once per process. We cache the in-flight/settled attempt so concurrent decodes
@@ -110,7 +138,12 @@ function isObject(value) {
 function isNumberArray(value) {
     return Array.isArray(value) && value.every(item => typeof item === 'number');
 }
-function fromBase64(b64) {
+const STRICT_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function fromBase64(b64, marker, context) {
+    if (marker && !STRICT_BASE64_PATTERN.test(b64)) {
+        throw new Error(`Invalid ${marker} envelope: b64 at path b64 must be well-formed base64; ` +
+            `${context ? `${context}; ` : ''}actual count unknown, actual type string with length ${b64.length}`);
+    }
     if (typeof Buffer !== 'undefined') {
         const buf = Buffer.from(b64, 'base64');
         return new Uint8Array(buf.buffer, buf.byteOffset, buf.length);
@@ -128,9 +161,9 @@ const ARROW_MISSING_MESSAGE = 'Received an Arrow-encoded payload but no Arrow de
     'Install the optional dependency with `npm install apache-arrow`, or set ' +
     'TYWRAP_CODEC_FALLBACK=json on the Python side to receive JSON instead ' +
     '(lossy for dtype/NA fidelity). tywrap never silently downgrades Arrow payloads.';
-function requireArrowDecoder() {
+function requireArrowDecoder(marker) {
     if (!arrowTableFrom) {
-        throw new Error(ARROW_MISSING_MESSAGE);
+        throw new ScientificDecodeError('arrow', marker, new Error(ARROW_MISSING_MESSAGE));
     }
     return arrowTableFrom;
 }
@@ -142,7 +175,7 @@ function requireArrowDecoder() {
  * for the rest of the process. If apache-arrow is absent we throw a clear, actionable
  * error rather than silently producing wrong data.
  */
-async function ensureArrowDecoder() {
+async function ensureArrowDecoder(marker) {
     if (arrowTableFrom) {
         return arrowTableFrom;
     }
@@ -150,17 +183,17 @@ async function ensureArrowDecoder() {
     lazyRegistration ??= autoRegisterArrowDecoder(lazyArrowLoaderOverride ? { loader: lazyArrowLoaderOverride } : {});
     await lazyRegistration;
     if (!arrowTableFrom) {
-        throw new Error(ARROW_MISSING_MESSAGE);
+        throw new ScientificDecodeError('arrow', marker, new Error(ARROW_MISSING_MESSAGE));
     }
     return arrowTableFrom;
 }
-async function tryDecodeArrowTable(bytes) {
-    const decoder = await ensureArrowDecoder();
+async function tryDecodeArrowTable(bytes, marker) {
+    const decoder = await ensureArrowDecoder(marker);
     try {
         return decoder(bytes);
     }
     catch (err) {
-        throw new Error(`Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw new ScientificDecodeError('arrow', marker, err, `Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 function isPromiseLike(value) {
@@ -199,8 +232,7 @@ function typedArrayToPlain(arr) {
     if (arr !== null && arr !== undefined && typeof arr === 'object' && Symbol.iterator in arr) {
         return Array.from(arr);
     }
-    // Non-iterable: return empty array (shouldn't happen with valid Arrow data)
-    return [];
+    return null;
 }
 /**
  * Extract values from an Arrow table as a plain JavaScript array.
@@ -222,6 +254,22 @@ function extractArrowValues(data) {
     }
     return null;
 }
+function extractNdarrayArrowValues(data, shape, dtype) {
+    try {
+        const values = extractArrowValues(data);
+        if (values) {
+            return values;
+        }
+    }
+    catch (error) {
+        throw new Error(`Invalid ndarray envelope: b64 decoded data extraction failed at path b64 for declared ` +
+            `shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; actual count unknown, ` +
+            `actual type ${actualType(data)} (${error instanceof Error ? error.message : String(error)})`);
+    }
+    throw new Error(`Invalid ndarray envelope: b64 decoded data at path b64 could not extract Arrow values ` +
+        `for declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; ` +
+        `actual count unknown, actual type ${actualType(data)}`);
+}
 /**
  * Reshape a flat array into a multi-dimensional nested array.
  *
@@ -256,6 +304,111 @@ function reshapeArray(flat, shape) {
 }
 // Why: decoding needs to reject incompatible envelopes before we attempt to interpret payloads.
 const CODEC_VERSION = 1;
+function isStrictV1Envelope(envelope) {
+    return envelope.codecVersion === CODEC_VERSION;
+}
+function actualType(value) {
+    if (Array.isArray(value)) {
+        return `array(length=${value.length})`;
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        return `number(${String(value)})`;
+    }
+    return typeof value;
+}
+function assertShape(shapeValue, marker, field = 'shape', dtype) {
+    if (!Array.isArray(shapeValue)) {
+        throw new Error(`Invalid ${marker} envelope: ${field} at path ${field} must be a list of ` +
+            `non-negative safe integers; declared shape ${String(shapeValue)} and dtype ` +
+            `${JSON.stringify(dtype)}, actual count unknown, actual type ${actualType(shapeValue)}`);
+    }
+    for (let i = 0; i < shapeValue.length; i += 1) {
+        const dim = shapeValue[i];
+        if (typeof dim !== 'number' || !Number.isSafeInteger(dim) || dim < 0) {
+            throw new Error(`Invalid ${marker} envelope: ${field}[${i}]=${String(dim)} must be a non-negative integer ` +
+                `within the safe range for declared shape ${JSON.stringify(shapeValue)}; ` +
+                `declared dtype ${JSON.stringify(dtype)}, actual count unknown, ` +
+                `actual type ${actualType(dim)} with value ${String(dim)}`);
+        }
+    }
+    return shapeValue;
+}
+function assertOptionalNonEmptyDtype(value, marker, field = 'dtype', shape) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid ${marker} envelope: ${field} at path ${field} must be a non-empty string; ` +
+            `declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(value)}, ` +
+            `actual count unknown, actual type ${actualType(value)}`);
+    }
+    return value;
+}
+function readEnvelopeShape(envelope, shapeValue, marker, field = 'shape', dtype) {
+    return isStrictV1Envelope(envelope)
+        ? assertShape(shapeValue, marker, field, dtype)
+        : isNumberArray(shapeValue)
+            ? shapeValue
+            : undefined;
+}
+function readEnvelopeDtype(envelope, dtypeValue, marker, field = 'dtype', shape) {
+    return isStrictV1Envelope(envelope)
+        ? assertOptionalNonEmptyDtype(dtypeValue, marker, field, shape)
+        : typeof dtypeValue === 'string'
+            ? dtypeValue
+            : undefined;
+}
+function countJsonLeaves(value) {
+    if (!Array.isArray(value)) {
+        return 1;
+    }
+    return value.reduce((count, item) => count + countJsonLeaves(item), 0);
+}
+function assertJsonMatchesShape(data, shape, dtype) {
+    const declaredCount = shapeProduct(shape);
+    const strictLeaves = dtype !== undefined;
+    const actualCount = strictLeaves ? countJsonLeaves(data) : undefined;
+    const visit = (value, depth, path) => {
+        if (depth === shape.length) {
+            if (strictLeaves && Array.isArray(value)) {
+                throw new Error(`Invalid ndarray envelope: data at path ${path} exceeds nesting depth ` +
+                    `${shape.length} for declared shape ${JSON.stringify(shape)} and dtype ` +
+                    `${JSON.stringify(dtype)}; actual count ${actualCount}, actual type ${actualType(value)}`);
+            }
+            return;
+        }
+        if (!Array.isArray(value)) {
+            throw new Error(`Invalid ndarray envelope: data at path ${path} must be an array at depth ${depth} ` +
+                `for declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; ` +
+                `actual count ${actualCount ?? 'unknown'}, actual type ${actualType(value)}`);
+        }
+        const expectedLength = shape[depth];
+        if (value.length !== expectedLength) {
+            throw new Error(`Invalid ndarray envelope: data at path ${path} has length ${value.length}, expected ` +
+                `${expectedLength} for declared shape ${JSON.stringify(shape)} and dtype ` +
+                `${JSON.stringify(dtype)}; declared count ${declaredCount}, actual count ${actualCount ?? 'unknown'}, ` +
+                `actual type ${actualType(value)}`);
+        }
+        value.forEach((item, index) => visit(item, depth + 1, `${path}[${index}]`));
+    };
+    visit(data, 0, 'data');
+    if (strictLeaves && actualCount !== declaredCount) {
+        throw new Error(`Invalid ndarray envelope: data at path data has leaf count ${actualCount}, expected ` +
+            `${declaredCount} for declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; ` +
+            `actual type ${actualType(data)}`);
+    }
+}
+function assertArrowCount(values, shape, dtype) {
+    const expected = shapeProduct(shape);
+    if (values.length !== expected) {
+        throw new Error(`Invalid ndarray envelope: b64 decoded data at path b64 has element count ${values.length}, ` +
+            `expected ${expected} for declared shape ${JSON.stringify(shape)} and dtype ` +
+            `${JSON.stringify(dtype)}; actual type array(length=${values.length})`);
+    }
+}
 function assertCodecVersion(envelope, typeTag) {
     if (!('codecVersion' in envelope)) {
         return;
@@ -284,8 +437,8 @@ function decodeArrowOrJsonEnvelope(value, decodeArrow, typeTag) {
         if (typeof b64 !== 'string') {
             throw new Error(`Invalid ${typeTag} envelope: missing b64`);
         }
-        const bytes = fromBase64(b64);
-        const decoded = decodeArrow(bytes);
+        const bytes = fromBase64(b64, isStrictV1Envelope(value) ? typeTag : undefined);
+        const decoded = decodeArrow(bytes, typeTag);
         return isPromiseLike(decoded)
             ? decoded.then(item => tagDecodedShape(item, { marker: typeTag }))
             : tagDecodedShape(decoded, { marker: typeTag });
@@ -300,43 +453,59 @@ function decodeArrowOrJsonEnvelope(value, decodeArrow, typeTag) {
 }
 const decodeDataframeEnvelope = (value, decodeArrow) => decodeArrowOrJsonEnvelope(value, decodeArrow, 'dataframe');
 const decodeSeriesEnvelope = (value, decodeArrow) => decodeArrowOrJsonEnvelope(value, decodeArrow, 'series');
+function finishNdarrayDecode(data, strictV1, shape, dtype, metadata) {
+    const values = strictV1
+        ? extractNdarrayArrowValues(data, shape, dtype)
+        : extractArrowValues(data);
+    if (!values) {
+        return tagDecodedShape(data, metadata);
+    }
+    if (strictV1) {
+        assertArrowCount(values, shape, dtype);
+    }
+    return tagDecodedShape(shape && shape.length !== 1 ? reshapeArray(values, shape) : values, metadata);
+}
 const decodeNdarrayEnvelope = (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 strictV1 = isStrictV1Envelope(value);
+    const shape = readEnvelopeShape(value, value.shape, 'ndarray', 'shape', value.dtype);
+    const dtype = readEnvelopeDtype(value, value.dtype, 'ndarray', 'dtype', shape);
     const metadata = { marker: 'ndarray', dims: shape?.length, dtype };
     if (encoding === 'arrow') {
+        if (strictV1 && dtype === undefined) {
+            throw new Error(`Invalid ndarray envelope: dtype at path dtype is required for Arrow encoding; ` +
+                `declared shape ${JSON.stringify(shape)} and dtype undefined, actual count unknown, actual type undefined`);
+        }
         const b64 = value.b64;
         if (typeof b64 !== 'string') {
-            throw new Error('Invalid ndarray envelope: missing b64');
+            if (!strictV1) {
+                throw new Error('Invalid ndarray envelope: missing b64');
+            }
+            throw new Error(`Invalid ndarray envelope: b64 at path b64 must be a base64 string for declared ` +
+                `shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; actual count unknown, ` +
+                `actual type ${actualType(b64)}`);
         }
-        const bytes = fromBase64(b64);
-        const decoded = decodeArrow(bytes);
+        const bytes = fromBase64(b64, strictV1 ? 'ndarray' : undefined, `declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}`);
+        const decoded = decodeArrow(bytes, 'ndarray');
         // Extract values from Arrow table and reshape if needed
         // Arrow only handles 1D arrays, so we flatten on encode and reshape here
         // Reshape for: scalars (shape.length === 0) and multi-dim (shape.length > 1)
         // Skip reshape for: 1D arrays (shape.length === 1) - return as-is
         if (isPromiseLike(decoded)) {
-            return decoded.then(data => {
-                const values = extractArrowValues(data);
-                if (!values) {
-                    return tagDecodedShape(data, metadata); // Fallback: keep provenance on raw data.
-                }
-                // Reshape scalars and multi-dimensional arrays, but not 1D
-                return tagDecodedShape(shape && shape.length !== 1 ? reshapeArray(values, shape) : values, metadata);
-            });
+            return decoded.then(data => finishNdarrayDecode(data, strictV1, shape, dtype, metadata));
         }
-        const values = extractArrowValues(decoded);
-        if (!values) {
-            return tagDecodedShape(decoded, metadata); // Fallback: keep provenance on raw data.
-        }
-        // Reshape scalars and multi-dimensional arrays, but not 1D
-        return tagDecodedShape(shape && shape.length !== 1 ? reshapeArray(values, shape) : values, metadata);
+        return finishNdarrayDecode(decoded, strictV1, shape, dtype, metadata);
     }
     if (encoding === 'json') {
         if (!('data' in value)) {
-            throw new Error('Invalid ndarray envelope: missing data');
+            if (!strictV1) {
+                throw new Error('Invalid ndarray envelope: missing data');
+            }
+            throw new Error(`Invalid ndarray envelope: data at path data is required for declared shape ` +
+                `${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; actual count 0, actual type undefined`);
+        }
+        if (strictV1) {
+            assertJsonMatchesShape(value.data, shape, dtype);
         }
         return tagDecodedShape(value.data, metadata);
     }
@@ -362,6 +531,43 @@ function assertIndexArrayInRange(arr, bound, label) {
         }
     }
 }
+function assertSparseDataDomain(data, dtype, shape) {
+    const expectsBoolean = dtype === 'bool' || dtype === 'bool_';
+    const integerMatch = /^(u?int)(\d*)$/.exec(dtype);
+    const expectsInteger = integerMatch !== null;
+    const expectsFloat = /^float\d*$/.test(dtype);
+    const width = integerMatch?.[2] ? Number(integerMatch[2]) : undefined;
+    const unsignedInteger = integerMatch?.[1] === 'uint';
+    let integerMin;
+    let integerMax;
+    if (width === 8 || width === 16 || width === 32) {
+        integerMin = unsignedInteger ? 0 : -(2 ** (width - 1));
+        integerMax = unsignedInteger ? 2 ** width - 1 : 2 ** (width - 1) - 1;
+    }
+    for (let i = 0; i < data.length; i += 1) {
+        const item = data[i];
+        if (typeof item === 'number' && !Number.isFinite(item)) {
+            throw new Error(`Invalid scipy.sparse envelope: data[${i}] at path data[${i}] must be finite for ` +
+                `declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; ` +
+                `actual count ${data.length}, actual type number with value ${String(item)}`);
+        }
+        const valid = expectsBoolean
+            ? typeof item === 'boolean'
+            : expectsInteger
+                ? typeof item === 'number' &&
+                    Number.isInteger(item) &&
+                    (integerMin === undefined || item >= integerMin) &&
+                    (integerMax === undefined || item <= integerMax)
+                : expectsFloat
+                    ? typeof item === 'number'
+                    : true;
+        if (!valid) {
+            throw new Error(`Invalid scipy.sparse envelope: data[${i}] at path data[${i}] is incompatible with ` +
+                `declared shape ${JSON.stringify(shape)} and dtype ${JSON.stringify(dtype)}; ` +
+                `actual count ${data.length}, actual type ${actualType(item)} with value ${String(item)}`);
+        }
+    }
+}
 const decodeScipySparseEnvelope = value => {
     const encoding = value.encoding;
     if (encoding !== 'json') {
@@ -371,7 +577,8 @@ const decodeScipySparseEnvelope = value => {
     if (format !== 'csr' && format !== 'csc' && format !== 'coo') {
         throw new Error(`Invalid scipy.sparse envelope: unsupported format ${String(format)}`);
     }
-    const shape = value.shape;
+    const strictV1 = isStrictV1Envelope(value);
+    const shape = readEnvelopeShape(value, value.shape, 'scipy.sparse', 'shape', value.dtype);
     if (!Array.isArray(shape) ||
         shape.length !== 2 ||
         typeof shape[0] !== 'number' ||
@@ -388,8 +595,14 @@ const decodeScipySparseEnvelope = value => {
     if (!Array.isArray(data)) {
         throw new Error('Invalid scipy.sparse envelope: data must be an array');
     }
-    const dtypeValue = value.dtype;
-    const dtype = typeof dtypeValue === 'string' ? dtypeValue : undefined;
+    const dtype = readEnvelopeDtype(value, value.dtype, 'scipy.sparse', 'dtype', shape);
+    if (strictV1 && dtype === undefined) {
+        throw new Error(`Invalid scipy.sparse envelope: dtype at path dtype is required for declared shape ` +
+            `${JSON.stringify(shape)}; actual count ${data.length}, actual type undefined`);
+    }
+    if (strictV1) {
+        assertSparseDataDomain(data, dtype, shape);
+    }
     if (format === 'coo') {
         const row = value.row;
         const col = value.col;
@@ -404,14 +617,14 @@ const decodeScipySparseEnvelope = value => {
         }
         assertIndexArrayInRange(row, rows, 'row');
         assertIndexArrayInRange(col, cols, 'col');
-        return {
+        return tagDecodedShape({
             format,
             shape,
             data,
             row,
             col,
             dtype,
-        };
+        }, { marker: 'scipy.sparse', dims: shape.length, dtype });
     }
     const indices = value.indices;
     const indptr = value.indptr;
@@ -454,14 +667,14 @@ const decodeScipySparseEnvelope = value => {
         throw new Error(`Invalid scipy.sparse envelope: indptr must end at data.length (${data.length})`);
     }
     assertIndexArrayInRange(indices, minorAxis, 'indices');
-    return {
+    return tagDecodedShape({
         format,
         shape,
         data,
         indices,
         indptr,
         dtype,
-    };
+    }, { marker: 'scipy.sparse', dims: shape.length, dtype });
 };
 /** Product of a shape's dimensions (the element count). [] (scalar) -> 1. */
 function shapeProduct(shape) {
@@ -479,40 +692,67 @@ const decodeTorchTensorEnvelope = (value, _decodeArrow, recurse) => {
     if (!isObject(nested) || nested.__tywrap__ !== 'ndarray') {
         throw new Error('Invalid torch.tensor envelope: value must be an ndarray envelope');
     }
-    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];
-            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 strictV1 = isStrictV1Envelope(value);
+    const shape = readEnvelopeShape(value, value.shape, 'torch.tensor', 'shape', value.dtype);
     const nestedShapeValue = nested.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 nestedShape = readEnvelopeShape(value, nestedShapeValue, 'torch.tensor', 'value.shape', nested.dtype);
+    const scalarNormalization = shape !== undefined &&
+        nestedShape !== undefined &&
+        ((shape.length === 0 && nestedShape.length === 1 && nestedShape[0] === 1) ||
+            (nestedShape.length === 0 && shape.length === 1 && shape[0] === 1));
+    const shapesEqual = shape !== undefined &&
+        nestedShape !== undefined &&
+        shape.length === nestedShape.length &&
+        shape.every((dim, index) => dim === nestedShape[index]);
+    const shapesDisagree = strictV1
+        ? !shapesEqual && !scalarNormalization
+        : shape !== undefined &&
+            nestedShape !== undefined &&
+            shapeProduct(shape) !== shapeProduct(nestedShape);
+    if (shape && nestedShape && shapesDisagree) {
+        throw new Error(`Invalid torch.tensor envelope: shape at path shape ${JSON.stringify(shape)} disagrees ` +
+            `with nested ndarray shape at path value.shape ${JSON.stringify(nestedShape)}; exact shapes are required ` +
+            `(except scalar []/[1]), declared dtypes ${JSON.stringify(value.dtype)}/${JSON.stringify(nested.dtype)}, ` +
+            `actual counts ${shapeProduct(shape)} and ${shapeProduct(nestedShape)}`);
+    }
+    const dtype = readEnvelopeDtype(value, value.dtype, 'torch.tensor', 'dtype', shape);
+    if (strictV1 && dtype === undefined) {
+        throw new Error(`Invalid torch.tensor envelope: dtype at path dtype is required for declared shape ` +
+            `${JSON.stringify(shape)}; actual count ${shapeProduct(shape)}, actual type undefined`);
+    }
+    if (strictV1 && 'dtype' in nested) {
+        assertOptionalNonEmptyDtype(nested.dtype, 'torch.tensor', 'value.dtype', nestedShape);
+    }
     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 sourceDtypeValue = value.sourceDtype;
+    if (sourceDtypeValue !== undefined &&
+        (typeof sourceDtypeValue !== 'string' || sourceDtypeValue.length === 0)) {
+        throw new Error('Invalid torch.tensor envelope: sourceDtype must be a non-empty string when provided');
+    }
+    const sourceDtype = typeof sourceDtypeValue === 'string' ? sourceDtypeValue : undefined;
+    const sourceDeviceValue = value.sourceDevice;
+    if (sourceDeviceValue !== undefined &&
+        (typeof sourceDeviceValue !== 'string' || sourceDeviceValue.length === 0)) {
+        throw new Error('Invalid torch.tensor envelope: sourceDevice must be a non-empty string when provided');
+    }
+    const sourceDevice = typeof sourceDeviceValue === 'string' ? sourceDeviceValue : undefined;
+    const finishTensorDecode = (data) => tagDecodedShape({
+        data,
+        shape,
+        dtype,
+        device,
+        ...(sourceDtype === undefined ? {} : { sourceDtype }),
+        ...(sourceDevice === undefined ? {} : { sourceDevice }),
+    }, { marker: 'torch.tensor', dims: shape?.length, dtype });
     const decoded = recurse(nested);
     if (isPromiseLike(decoded)) {
-        return decoded.then(data => ({ data, shape, dtype, device }));
+        return decoded.then(finishTensorDecode);
     }
-    return { data: decoded, shape, dtype, device };
+    return finishTensorDecode(decoded);
 };
 /**
  * Recursively assert a value is plain JSON (null | boolean | number | string |
@@ -562,8 +802,14 @@ const decodeSklearnEstimatorEnvelope = value => {
     const className = value.className;
     const module = value.module;
     const params = value.params;
-    if (typeof className !== 'string' || typeof module !== 'string' || !isObject(params)) {
-        throw new Error('Invalid sklearn.estimator envelope: expected className/module strings + params object');
+    const strictV1 = isStrictV1Envelope(value);
+    if (typeof className !== 'string' ||
+        typeof module !== 'string' ||
+        (strictV1 && (className.length === 0 || module.length === 0)) ||
+        !isObject(params)) {
+        throw new Error(`Invalid sklearn.estimator envelope: expected className/module strings + params object; ` +
+            `className at path className and module at path module must be non-empty; declared class ${JSON.stringify(className)}, ` +
+            `declared module ${JSON.stringify(module)}, actual types ${actualType(className)}/${actualType(module)}`);
     }
     // 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
@@ -581,12 +827,12 @@ const decodeSklearnEstimatorEnvelope = value => {
         throw new Error('Invalid sklearn.estimator envelope: version must be a string when provided');
     }
     const version = typeof versionValue === 'string' ? versionValue : undefined;
-    return {
+    return tagDecodedShape({
         className,
         module,
         version,
         params,
-    };
+    }, { marker: 'sklearn.estimator' });
 };
 // Why: dispatch over the __tywrap__ typeTag instead of a long if-chain so each type's
 // decode logic lives in one focused handler. The typeTag strings are the on-the-wire keys
@@ -600,20 +846,48 @@ const ENVELOPE_HANDLERS = new Map([
     ['torch.tensor', decodeTorchTensorEnvelope],
     ['sklearn.estimator', decodeSklearnEstimatorEnvelope],
 ]);
+const MAX_DECODE_DEPTH = 2048;
+const MAX_DECODE_NODES = 1_000_000;
+function isPlainObject(value) {
+    if (!isObject(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function isPlainArray(value) {
+    return Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+}
+function decodePath(base, key) {
+    if (typeof key === 'number') {
+        return `${base}[${key}]`;
+    }
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? `${base}.${key}` : `${base}[${JSON.stringify(key)}]`;
+}
 function decodeEnvelopeCore(value, decodeArrow, recurse) {
     if (!isObject(value)) {
         return value;
     }
     const typeTag = value.__tywrap__;
-    if (typeof typeTag !== 'string') {
+    if (!isScientificMarker(typeTag)) {
         return value;
     }
     const handler = ENVELOPE_HANDLERS.get(typeTag);
     if (!handler) {
         return value;
     }
-    assertCodecVersion(value, typeTag);
-    return handler(value, decodeArrow, recurse);
+    try {
+        assertCodecVersion(value, typeTag);
+        const decoded = handler(value, decodeArrow, recurse);
+        return isPromiseLike(decoded)
+            ? Promise.resolve(decoded).catch(error => {
+                throw asScientificDecodeError(error, typeTag);
+            })
+            : decoded;
+    }
+    catch (error) {
+        throw asScientificDecodeError(error, typeTag);
+    }
 }
 function decodeEnvelope(value, decodeArrow) {
     const recurse = v => decodeEnvelopeCore(v, decodeArrow, recurse);
@@ -624,26 +898,167 @@ function decodeEnvelope(value, decodeArrow) {
     return decoded;
 }
 async function decodeEnvelopeAsync(value, decodeArrow) {
-    const recurse = v => decodeEnvelopeCore(v, decodeArrow, recurse);
-    return await decodeEnvelopeCore(value, decodeArrow, recurse);
+    let visitedNodes = 0;
+    const recordVisit = (depth, path) => {
+        visitedNodes += 1;
+        if (visitedNodes > MAX_DECODE_NODES) {
+            throw new Error(`Scientific envelope decode maximum visited nodes ${MAX_DECODE_NODES} exceeded at ${path}`);
+        }
+        if (depth > MAX_DECODE_DEPTH) {
+            throw new Error(`Scientific envelope decode maximum depth ${MAX_DECODE_DEPTH} exceeded at ${path}`);
+        }
+    };
+    const prefixHandlerError = (error, path) => {
+        if (path === 'result') {
+            throw error;
+        }
+        throw new ScientificDecodeError('envelope', 'unknown', error, `Scientific envelope decode failed at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    };
+    const assignDecoded = (target, original, decoded) => {
+        if (decoded !== original) {
+            if (Array.isArray(target.container)) {
+                target.container[target.key] = decoded;
+            }
+            else {
+                target.container[target.key] = decoded;
+            }
+        }
+    };
+    const settleDecoded = async (decoded, original, target, path) => {
+        let resolved;
+        try {
+            resolved = await decoded;
+        }
+        catch (error) {
+            return prefixHandlerError(error, path);
+        }
+        assignDecoded(target, original, resolved);
+    };
+    const decodeSingle = (item, depth, path) => {
+        // Handlers sometimes decode a required child envelope themselves (currently
+        // torch.tensor.value). Keep that single-envelope recursion unchanged.
+        const recurseSingle = nested => {
+            const nestedPath = decodePath(path, 'value');
+            recordVisit(depth + 1, nestedPath);
+            return decodeEnvelopeCore(nested, decodeArrow, recurseSingle);
+        };
+        return decodeEnvelopeCore(item, decodeArrow, recurseSingle);
+    };
+    const frames = [];
+    const pending = [];
+    const visit = (current, depth, path, target) => {
+        const plainArray = isPlainArray(current);
+        const plainObject = isPlainObject(current);
+        // Only containers consume the traversal budget. Primitive leaves are already
+        // bounded by the payload byte cap, and counting them would reject large plain
+        // arrays that decoded fine before recursion existed.
+        if (plainArray || plainObject) {
+            recordVisit(depth, path);
+        }
+        if (plainObject && typeof current.__tywrap__ === 'string') {
+            if (!isScientificMarker(current.__tywrap__)) {
+                return;
+            }
+            let decoded;
+            try {
+                decoded = decodeSingle(current, depth, path);
+            }
+            catch (error) {
+                return prefixHandlerError(error, path);
+            }
+            if (isPromiseLike(decoded)) {
+                if (target) {
+                    pending.push(settleDecoded(decoded, current, target, path));
+                }
+                else {
+                    pending.push(settleDecoded(decoded, current, { container: root, key: 'value' }, path));
+                }
+            }
+            else if (target) {
+                assignDecoded(target, current, decoded);
+            }
+            else if (decoded !== current) {
+                root.value = decoded;
+            }
+            return;
+        }
+        if (plainArray) {
+            frames.push({ kind: 'array', container: current, depth, path, nextIndex: 0 });
+        }
+        else if (plainObject) {
+            frames.push({
+                kind: 'object',
+                container: current,
+                depth,
+                path,
+                entries: Object.entries(current),
+                nextIndex: 0,
+            });
+        }
+    };
+    /**
+     * Values have copy semantics across the bridge: repeated Python references are
+     * serialized independently, and this decoder does not restore alias identity.
+     */
+    const root = { value };
+    visit(value, 0, 'result');
+    const visitChild = (item, key, target, frame) => {
+        try {
+            visit(item, frame.depth + 1, decodePath(frame.path, key), target);
+        }
+        catch (error) {
+            pending.push(Promise.reject(error));
+        }
+    };
+    while (frames.length > 0) {
+        const frame = frames[frames.length - 1];
+        if (!frame) {
+            break;
+        }
+        if (frame.nextIndex >= (frame.kind === 'array' ? frame.container.length : frame.entries.length)) {
+            frames.pop();
+            continue;
+        }
+        const index = frame.nextIndex;
+        frame.nextIndex += 1;
+        if (frame.kind === 'array') {
+            visitChild(frame.container[index], index, { container: frame.container, key: index }, frame);
+        }
+        else {
+            const entry = frame.entries[index];
+            if (entry) {
+                const [key, item] = entry;
+                visitChild(item, key, { container: frame.container, key }, frame);
+            }
+        }
+    }
+    if (pending.length > 0) {
+        await Promise.all(pending);
+    }
+    return root.value;
 }
 /**
  * Decode values produced by the Python bridge.
  */
 export async function decodeValueAsync(value) {
-    return await decodeEnvelopeAsync(value, tryDecodeArrowTable);
+    try {
+        return await decodeEnvelopeAsync(value, tryDecodeArrowTable);
+    }
+    catch (error) {
+        throw asScientificDecodeError(error, 'unknown');
+    }
 }
 /**
  * Synchronous decode. Arrow decoding requires a registered decoder.
  */
 export function decodeValue(value) {
-    const decodeArrow = (bytes) => {
-        const decoder = requireArrowDecoder();
+    const decodeArrow = (bytes, marker) => {
+        const decoder = requireArrowDecoder(marker);
         try {
             return decoder(bytes);
         }
         catch (err) {
-            throw new Error(`Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
+            throw new ScientificDecodeError('arrow', marker, err, `Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
     return decodeEnvelope(value, decodeArrow);