runmat_runtime/builtins/io/json/

jsonencode.rs

//! MATLAB-compatible `jsonencode` builtin for serialising RunMat values to JSON text.

use std::collections::BTreeMap;
use std::fmt::Write as FmtWrite;

use runmat_builtins::{
    BuiltinCompletionPolicy, BuiltinDescriptor, BuiltinErrorDescriptor, BuiltinExtensionDescriptor,
    BuiltinExtensionMode, BuiltinIntegerBackendRule, BuiltinIntegerCapabilityDescriptor,
    BuiltinIntegerComputationDomain, BuiltinIntegerInputAvailability,
    BuiltinIntegerInputCapability, BuiltinIntegerOutputClassRule, BuiltinIntegerOverflowRule,
    BuiltinIntegerOverloadKind, BuiltinIntegerScalarDoubleRule, BuiltinOutputMode,
    BuiltinParamArity, BuiltinParamDescriptor, BuiltinParamType, BuiltinSignatureDescriptor,
};
use runmat_macros::runtime_builtin;
use runmat_value::{
    CellArray, CharArray, ComplexTensor, IntValue, IntegerStorage, LogicalArray, ObjectInstance,
    StringArray, StructValue, SymbolicArray, Tensor, Value,
};

use crate::builtins::common::spec::{
    BroadcastSemantics, BuiltinFusionSpec, BuiltinGpuSpec, ConstantStrategy, GpuOpKind,
    ReductionNaN, ResidencyPolicy, ShapeRequirements,
};
use crate::builtins::common::tensor;
use crate::{build_runtime_error, gather_if_needed_async, BuiltinResult, RuntimeError};

const BUILTIN_NAME: &str = "jsonencode";

const JSONENCODE_RESIDENT_INPUT_EXTENSION: BuiltinExtensionDescriptor =
    BuiltinExtensionDescriptor {
        id: "jsonencode-resident-input",
        mode: BuiltinExtensionMode::RunMatOnly,
        description: "jsonencode with explicit gpuArray input is a RunMat extension",
        error_identifier: Some("RunMat:compatibility:JsonencodeResidentInputExtension"),
    };
const JSONENCODE_TYPED_INTEGER_OPTION_EXTENSION: BuiltinExtensionDescriptor =
    BuiltinExtensionDescriptor {
        id: "jsonencode-typed-integer-option",
        mode: BuiltinExtensionMode::RunMatOnly,
        description: "jsonencode with a typed-integer boolean option is a RunMat extension",
        error_identifier: Some("RunMat:compatibility:JsonencodeTypedIntegerOptionExtension"),
    };
const JSONENCODE_NUMERIC_OPTION_EXTENSION: BuiltinExtensionDescriptor =
    BuiltinExtensionDescriptor {
        id: "jsonencode-numeric-option",
        mode: BuiltinExtensionMode::RunMatOnly,
        description: "jsonencode with a floating numeric boolean option is a RunMat extension",
        error_identifier: Some("RunMat:compatibility:JsonencodeNumericOptionExtension"),
    };
const JSONENCODE_TEXT_OPTION_EXTENSION: BuiltinExtensionDescriptor = BuiltinExtensionDescriptor {
    id: "jsonencode-text-option",
    mode: BuiltinExtensionMode::RunMatOnly,
    description: "jsonencode with a textual boolean option is a RunMat extension",
    error_identifier: Some("RunMat:compatibility:JsonencodeTextOptionExtension"),
};
const JSONENCODE_COMPLEX_INPUT_EXTENSION: BuiltinExtensionDescriptor = BuiltinExtensionDescriptor {
    id: "jsonencode-complex-input",
    mode: BuiltinExtensionMode::RunMatOnly,
    description: "jsonencode complex-number object encoding is a RunMat extension",
    error_identifier: Some("RunMat:compatibility:JsonencodeComplexInputExtension"),
};
const JSONENCODE_SPARSE_INPUT_EXTENSION: BuiltinExtensionDescriptor = BuiltinExtensionDescriptor {
    id: "jsonencode-sparse-input",
    mode: BuiltinExtensionMode::RunMatOnly,
    description: "jsonencode sparse-array densification is a RunMat extension",
    error_identifier: Some("RunMat:compatibility:JsonencodeSparseInputExtension"),
};
pub const JSONENCODE_EXTENSIONS: [BuiltinExtensionDescriptor; 6] = [
    JSONENCODE_RESIDENT_INPUT_EXTENSION,
    JSONENCODE_TYPED_INTEGER_OPTION_EXTENSION,
    JSONENCODE_NUMERIC_OPTION_EXTENSION,
    JSONENCODE_TEXT_OPTION_EXTENSION,
    JSONENCODE_COMPLEX_INPUT_EXTENSION,
    JSONENCODE_SPARSE_INPUT_EXTENSION,
];

const JSONENCODE_REAL_INTEGER_INPUT: [BuiltinIntegerInputCapability; 1] =
    [BuiltinIntegerInputCapability {
        name: "value",
        classes: &crate::builtins::common::integer_capability::ALL_INTEGER_CLASSES,
        availability: BuiltinIntegerInputAvailability::Documented,
        scalar_double: BuiltinIntegerScalarDoubleRule::NotApplicable,
        notes: "All eight real integer classes serialize from authoritative storage to exact signed or unsigned JSON decimal literals.",
    }];
const JSONENCODE_INTEGER_OPTION_INPUT: [BuiltinIntegerInputCapability; 1] =
    [BuiltinIntegerInputCapability {
        name: "PrettyPrint_or_ConvertInfAndNaN",
        classes: &crate::builtins::common::integer_capability::ALL_INTEGER_CLASSES,
        availability: BuiltinIntegerInputAvailability::RunMatOnly,
        scalar_double: BuiltinIntegerScalarDoubleRule::Allowed,
        notes: "MATLAB-compatible mode requires logical option values; RunMat mode treats exact integer zero as false and every nonzero integer as true.",
    }];
const JSONENCODE_COMPLEX_INTEGER_INPUT: [BuiltinIntegerInputCapability; 1] =
    [BuiltinIntegerInputCapability {
        name: "value",
        classes: &crate::builtins::common::integer_capability::ALL_INTEGER_CLASSES,
        availability: BuiltinIntegerInputAvailability::RunMatOnly,
        scalar_double: BuiltinIntegerScalarDoubleRule::NotApplicable,
        notes: "The public jsonencode contract rejects complex numeric data. RunMat mode retains its exact {real,imag} object encoding for paired integer storage.",
    }];
pub const JSONENCODE_INTEGER_CAPABILITIES: [BuiltinIntegerCapabilityDescriptor; 3] = [
    BuiltinIntegerCapabilityDescriptor {
        form: "jsonText = jsonencode(full_real_integer_value)",
        inputs: &JSONENCODE_REAL_INTEGER_INPUT,
        computation_domain: BuiltinIntegerComputationDomain::ExactInteger,
        output_class: BuiltinIntegerOutputClassRule::FunctionSpecific,
        overflow: BuiltinIntegerOverflowRule::Error,
        backend: BuiltinIntegerBackendRule::GatherFallback,
        overload: BuiltinIntegerOverloadKind::Multiple,
        notes: "Host and automatically resident integer values serialize exactly. Explicit gpuArray input is independently compatibility-gated before owner access; accepted resident values gather through their owner at the serialization sink.",
    },
    BuiltinIntegerCapabilityDescriptor {
        form: "jsonText = jsonencode(value, option, integer_flag)",
        inputs: &JSONENCODE_INTEGER_OPTION_INPUT,
        computation_domain: BuiltinIntegerComputationDomain::Predicate,
        output_class: BuiltinIntegerOutputClassRule::FunctionSpecific,
        overflow: BuiltinIntegerOverflowRule::NotApplicable,
        backend: BuiltinIntegerBackendRule::GatherFallback,
        overload: BuiltinIntegerOverloadKind::ScalarOnly,
        notes: "Typed numeric option coercion is a RunMat convenience and is gated before resident access.",
    },
    BuiltinIntegerCapabilityDescriptor {
        form: "jsonText = jsonencode(complex_integer_value)",
        inputs: &JSONENCODE_COMPLEX_INTEGER_INPUT,
        computation_domain: BuiltinIntegerComputationDomain::ExactInteger,
        output_class: BuiltinIntegerOutputClassRule::FunctionSpecific,
        overflow: BuiltinIntegerOverflowRule::Error,
        backend: BuiltinIntegerBackendRule::GatherFallback,
        overload: BuiltinIntegerOverloadKind::Multiple,
        notes: "Complex JSON encoding is outside the public compatibility surface and requires the complex-input extension; integer components remain exact in RunMat mode.",
    },
];

const JSONENCODE_OUTPUT: [BuiltinParamDescriptor; 1] = [BuiltinParamDescriptor {
    name: "jsonText",
    ty: BuiltinParamType::StringScalar,
    arity: BuiltinParamArity::Required,
    default: None,
    description: "JSON text encoded as a character row vector.",
}];
const JSONENCODE_INPUTS_VALUE: [BuiltinParamDescriptor; 1] = [BuiltinParamDescriptor {
    name: "value",
    ty: BuiltinParamType::Any,
    arity: BuiltinParamArity::Required,
    default: None,
    description: "Value to encode as JSON.",
}];
const JSONENCODE_INPUTS_VALUE_OPTIONS: [BuiltinParamDescriptor; 2] = [
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Value to encode as JSON.",
    },
    BuiltinParamDescriptor {
        name: "options",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Options struct with fields such as PrettyPrint and ConvertInfAndNaN.",
    },
];
const JSONENCODE_INPUTS_VALUE_NAME_VALUE: [BuiltinParamDescriptor; 3] = [
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Value to encode as JSON.",
    },
    BuiltinParamDescriptor {
        name: "name",
        ty: BuiltinParamType::StringScalar,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Option name (for example \"PrettyPrint\" or \"ConvertInfAndNaN\").",
    },
    BuiltinParamDescriptor {
        name: "optionValue",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Option value for the preceding option name.",
    },
];
const JSONENCODE_INPUTS_VALUE_NAME_VALUE_VARIADIC: [BuiltinParamDescriptor; 2] = [
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Value to encode as JSON.",
    },
    BuiltinParamDescriptor {
        name: "nameValuePairs...",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Variadic,
        default: None,
        description: "Name-value option pairs.",
    },
];
const JSONENCODE_SIGNATURES: [BuiltinSignatureDescriptor; 4] = [
    BuiltinSignatureDescriptor {
        label: "jsonText = jsonencode(value)",
        inputs: &JSONENCODE_INPUTS_VALUE,
        outputs: &JSONENCODE_OUTPUT,
    },
    BuiltinSignatureDescriptor {
        label: "jsonText = jsonencode(value, options)",
        inputs: &JSONENCODE_INPUTS_VALUE_OPTIONS,
        outputs: &JSONENCODE_OUTPUT,
    },
    BuiltinSignatureDescriptor {
        label: "jsonText = jsonencode(value, name, optionValue)",
        inputs: &JSONENCODE_INPUTS_VALUE_NAME_VALUE,
        outputs: &JSONENCODE_OUTPUT,
    },
    BuiltinSignatureDescriptor {
        label: "jsonText = jsonencode(value, nameValuePairs...)",
        inputs: &JSONENCODE_INPUTS_VALUE_NAME_VALUE_VARIADIC,
        outputs: &JSONENCODE_OUTPUT,
    },
];
const JSONENCODE_ERROR_OPTIONS_CONFIG: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.OPTIONS_CONFIG",
    identifier: None,
    when: "Single options argument is provided but is not a struct.",
    message: "jsonencode: expected name/value pairs or options struct",
};
const JSONENCODE_ERROR_NAME_VALUE_PAIRS: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.NAME_VALUE_PAIRS",
    identifier: None,
    when: "Name-value options do not come in pairs.",
    message: "jsonencode: name/value pairs must come in pairs",
};
const JSONENCODE_ERROR_OPTION_NAME: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.OPTION_NAME",
    identifier: None,
    when: "Option name is not a character vector or string scalar.",
    message: "jsonencode: option names must be character vectors or strings",
};
const JSONENCODE_ERROR_OPTION_VALUE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.OPTION_VALUE",
    identifier: None,
    when: "Option value is not a scalar logical/numeric or boolean-like text.",
    message: "jsonencode: option value must be scalar logical or numeric",
};
const JSONENCODE_ERROR_UNKNOWN_OPTION: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.UNKNOWN_OPTION",
    identifier: None,
    when: "Option name is not recognized.",
    message: "jsonencode: unknown option name",
};
const JSONENCODE_ERROR_INF_NAN: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.INF_NAN",
    identifier: None,
    when: "Input contains NaN/Inf while ConvertInfAndNaN is false.",
    message: "jsonencode: ConvertInfAndNaN must be true to encode NaN or Inf values",
};
const JSONENCODE_ERROR_UNSUPPORTED_TYPE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.UNSUPPORTED_TYPE",
    identifier: None,
    when: "Input value type is not supported for JSON encoding.",
    message:
        "jsonencode: unsupported input type; expected numeric, logical, string, struct, cell, or object data",
};
const JSONENCODE_ERROR_UNEXPECTED_GPU: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.UNEXPECTED_GPU",
    identifier: None,
    when: "A GPU tensor handle reaches encoding after gather pass.",
    message: "jsonencode: unexpected gpuArray handle after gather pass",
};
const JSONENCODE_ERROR_INTERNAL: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.JSONENCODE.INTERNAL",
    identifier: None,
    when: "Internal JSON conversion or container materialization fails.",
    message: "jsonencode: internal conversion failed",
};
const JSONENCODE_ERRORS: [BuiltinErrorDescriptor; 9] = [
    JSONENCODE_ERROR_OPTIONS_CONFIG,
    JSONENCODE_ERROR_NAME_VALUE_PAIRS,
    JSONENCODE_ERROR_OPTION_NAME,
    JSONENCODE_ERROR_OPTION_VALUE,
    JSONENCODE_ERROR_UNKNOWN_OPTION,
    JSONENCODE_ERROR_INF_NAN,
    JSONENCODE_ERROR_UNSUPPORTED_TYPE,
    JSONENCODE_ERROR_UNEXPECTED_GPU,
    JSONENCODE_ERROR_INTERNAL,
];
pub const JSONENCODE_DESCRIPTOR: BuiltinDescriptor = BuiltinDescriptor {
    signatures: &JSONENCODE_SIGNATURES,
    output_mode: BuiltinOutputMode::Fixed,
    completion_policy: BuiltinCompletionPolicy::Public,
    errors: &JSONENCODE_ERRORS,
};

#[allow(clippy::too_many_lines)]
#[runmat_macros::register_gpu_spec(builtin_path = "crate::builtins::io::json::jsonencode")]
pub const GPU_SPEC: BuiltinGpuSpec = BuiltinGpuSpec {
    name: "jsonencode",
    op_kind: GpuOpKind::Custom("serialization"),
    supported_precisions: &[],
    broadcast: BroadcastSemantics::None,
    provider_hooks: &[],
    constant_strategy: ConstantStrategy::InlineLiteral,
    residency: ResidencyPolicy::GatherImmediately,
    nan_mode: ReductionNaN::Include,
    two_pass_threshold: None,
    workgroup_size: None,
    accepts_nan_mode: false,
    notes:
        "Serialization sink that gathers GPU data to host memory before emitting UTF-8 JSON text.",
};

fn jsonencode_error(error: &'static BuiltinErrorDescriptor) -> RuntimeError {
    jsonencode_error_with(error, error.message)
}

fn jsonencode_error_with(
    error: &'static BuiltinErrorDescriptor,
    message: impl Into<String>,
) -> RuntimeError {
    let mut builder = build_runtime_error(message).with_builtin(BUILTIN_NAME);
    if let Some(identifier) = error.identifier {
        builder = builder.with_identifier(identifier);
    }
    builder.build()
}

fn jsonencode_flow_with_context(err: RuntimeError) -> RuntimeError {
    let mut builder = build_runtime_error(err.message().to_string()).with_builtin(BUILTIN_NAME);
    if let Some(identifier) = err.identifier() {
        builder = builder.with_identifier(identifier.to_string());
    }
    builder.with_source(err).build()
}

#[runmat_macros::register_fusion_spec(builtin_path = "crate::builtins::io::json::jsonencode")]
pub const FUSION_SPEC: BuiltinFusionSpec = BuiltinFusionSpec {
    name: "jsonencode",
    shape: ShapeRequirements::Any,
    constant_strategy: ConstantStrategy::InlineLiteral,
    elementwise: None,
    reduction: None,
    emits_nan: false,
    notes: "jsonencode is a residency sink and never participates in fusion planning.",
};

#[derive(Debug, Clone)]
struct JsonEncodeOptions {
    pretty_print: bool,
    convert_inf_and_nan: bool,
}

impl Default for JsonEncodeOptions {
    fn default() -> Self {
        Self {
            pretty_print: false,
            convert_inf_and_nan: true,
        }
    }
}

#[derive(Debug, Clone)]
enum JsonValue {
    Null,
    Bool(bool),
    Number(JsonNumber),
    String(String),
    Array(Vec<JsonValue>),
    Object(Vec<(String, JsonValue)>),
}

#[derive(Debug, Clone)]
enum JsonNumber {
    Float(f64),
    I64(i64),
    U64(u64),
}

#[runtime_builtin(
    name = "jsonencode",
    category = "io/json",
    summary = "Serialize MATLAB values to UTF-8 JSON text.",
    keywords = "jsonencode,json,serialization,struct,gpu",
    accel = "cpu",
    type_resolver(crate::builtins::io::type_resolvers::jsonencode_type),
    descriptor(crate::builtins::io::json::jsonencode::JSONENCODE_DESCRIPTOR),
    extensions(crate::builtins::io::json::jsonencode::JSONENCODE_EXTENSIONS),
    integer_capabilities(crate::builtins::io::json::jsonencode::JSONENCODE_INTEGER_CAPABILITIES),
    builtin_path = "crate::builtins::io::json::jsonencode"
)]
async fn jsonencode_builtin(value: Value, rest: Vec<Value>) -> crate::BuiltinResult<Value> {
    validate_option_layout(&rest)?;
    preflight_jsonencode_extensions(&value, &rest)?;
    let host_value = gather_if_needed_async(&value)
        .await
        .map_err(jsonencode_flow_with_context)?;
    let mut gathered_args = Vec::with_capacity(rest.len());
    for value in &rest {
        gathered_args.push(
            gather_if_needed_async(value)
                .await
                .map_err(jsonencode_flow_with_context)?,
        );
    }

    preflight_option_extensions(&gathered_args)?;
    let options = parse_options(&gathered_args)?;
    let json_value = value_to_json(&host_value, &options)?;
    let json_string = render_json(&json_value, &options);

    Ok(Value::CharArray(CharArray::new_row(&json_string)))
}

fn preflight_jsonencode_extensions(value: &Value, rest: &[Value]) -> BuiltinResult<()> {
    if value_contains_complex(value) {
        crate::compatibility::ensure_builtin_extension_enabled(
            &JSONENCODE_COMPLEX_INPUT_EXTENSION,
            BUILTIN_NAME,
        )?;
    }
    if value_contains_sparse(value) {
        crate::compatibility::ensure_builtin_extension_enabled(
            &JSONENCODE_SPARSE_INPUT_EXTENSION,
            BUILTIN_NAME,
        )?;
    }
    preflight_option_extensions(rest)?;
    if value_contains_explicit_gpu(value) || rest.iter().any(value_contains_explicit_gpu) {
        crate::compatibility::ensure_builtin_extension_enabled(
            &JSONENCODE_RESIDENT_INPUT_EXTENSION,
            BUILTIN_NAME,
        )?;
    }
    Ok(())
}

fn validate_option_layout(rest: &[Value]) -> BuiltinResult<()> {
    if rest.is_empty() {
        return Ok(());
    }
    if rest.len() == 1 {
        return match &rest[0] {
            Value::Struct(options) => {
                for name in options.fields.keys() {
                    ensure_known_option(name)?;
                }
                Ok(())
            }
            _ => Err(jsonencode_error(&JSONENCODE_ERROR_OPTIONS_CONFIG)),
        };
    }
    if !rest.len().is_multiple_of(2) {
        return Err(jsonencode_error(&JSONENCODE_ERROR_NAME_VALUE_PAIRS));
    }
    for pair in rest.chunks_exact(2) {
        let name = option_name(&pair[0])?;
        ensure_known_option(&name)?;
    }
    Ok(())
}

fn ensure_known_option(name: &str) -> BuiltinResult<()> {
    if name.eq_ignore_ascii_case("PrettyPrint") || name.eq_ignore_ascii_case("ConvertInfAndNaN") {
        Ok(())
    } else {
        Err(jsonencode_error_with(
            &JSONENCODE_ERROR_UNKNOWN_OPTION,
            format!("{} ('{}')", JSONENCODE_ERROR_UNKNOWN_OPTION.message, name),
        ))
    }
}

fn preflight_option_extensions(rest: &[Value]) -> BuiltinResult<()> {
    for (name, option_value) in raw_options(rest)? {
        if !option_value_is_scalar(option_value) {
            return Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE));
        }
        if is_typed_integer_option(option_value) {
            crate::compatibility::ensure_builtin_extension_enabled(
                &JSONENCODE_TYPED_INTEGER_OPTION_EXTENSION,
                BUILTIN_NAME,
            )?;
        } else if is_floating_numeric_option(option_value)
            && !(name.eq_ignore_ascii_case("ConvertInfAndNaN")
                && is_documented_numeric_bool(option_value))
        {
            crate::compatibility::ensure_builtin_extension_enabled(
                &JSONENCODE_NUMERIC_OPTION_EXTENSION,
                BUILTIN_NAME,
            )?;
        } else if is_text_option(option_value) {
            crate::compatibility::ensure_builtin_extension_enabled(
                &JSONENCODE_TEXT_OPTION_EXTENSION,
                BUILTIN_NAME,
            )?;
        }
    }
    Ok(())
}

fn raw_options(rest: &[Value]) -> BuiltinResult<Vec<(String, &Value)>> {
    if let [Value::Struct(options)] = rest {
        return Ok(options
            .fields
            .iter()
            .map(|(name, value)| (name.clone(), value))
            .collect());
    }
    rest.chunks_exact(2)
        .map(|pair| option_name(&pair[0]).map(|name| (name, &pair[1])))
        .collect()
}

fn option_value_is_scalar(value: &Value) -> bool {
    match value {
        Value::Bool(_) | Value::Int(_) | Value::Num(_) | Value::String(_) => true,
        Value::Tensor(tensor) => tensor::is_scalar_tensor(tensor),
        Value::LogicalArray(logical) => logical.data.len() == 1,
        Value::CharArray(chars) => chars.rows == 1,
        Value::StringArray(strings) => strings.data.len() == 1,
        Value::GpuTensor(handle) => handle.shape.iter().copied().product::<usize>() == 1,
        _ => false,
    }
}

fn is_documented_numeric_bool(value: &Value) -> bool {
    let number = match value {
        Value::Num(number) => Some(*number),
        Value::Tensor(tensor) if tensor::is_scalar_tensor(tensor) => {
            Some(tensor::tensor_value_f64(tensor, 0))
        }
        _ => None,
    };
    matches!(number, Some(0.0 | 1.0))
}

fn is_typed_integer_option(value: &Value) -> bool {
    match value {
        Value::Int(_) => true,
        Value::Tensor(tensor) => tensor.integer_storage().is_some(),
        Value::GpuTensor(handle) => runmat_accelerate_api::handle_integer_type(handle).is_some(),
        _ => false,
    }
}

fn is_floating_numeric_option(value: &Value) -> bool {
    match value {
        Value::Num(_) => true,
        Value::Tensor(tensor) => tensor.integer_storage().is_none(),
        Value::GpuTensor(_) => false,
        _ => false,
    }
}

fn is_text_option(value: &Value) -> bool {
    matches!(
        value,
        Value::String(_) | Value::StringArray(_) | Value::CharArray(_)
    )
}

fn value_contains_complex(value: &Value) -> bool {
    match value {
        Value::Complex(_, _) | Value::ComplexTensor(_) => true,
        Value::GpuTensor(handle) => {
            runmat_accelerate_api::handle_storage(handle)
                != runmat_accelerate_api::GpuTensorStorage::Real
        }
        Value::Cell(cell) => cell.data.iter().any(value_contains_complex),
        Value::Struct(struct_value) => struct_value.fields.values().any(value_contains_complex),
        Value::Object(object) => object.properties.values().any(value_contains_complex),
        _ => false,
    }
}

fn value_contains_sparse(value: &Value) -> bool {
    match value {
        Value::SparseTensor(_) => true,
        Value::Cell(cell) => cell.data.iter().any(value_contains_sparse),
        Value::Struct(value) => value.fields.values().any(value_contains_sparse),
        Value::Object(value) => value.properties.values().any(value_contains_sparse),
        _ => false,
    }
}

fn value_contains_explicit_gpu(value: &Value) -> bool {
    match value {
        Value::GpuTensor(handle) => runmat_accelerate_api::handle_is_explicit(handle),
        Value::Cell(cell) => cell.data.iter().any(value_contains_explicit_gpu),
        Value::Struct(value) => value.fields.values().any(value_contains_explicit_gpu),
        Value::Object(value) => value.properties.values().any(value_contains_explicit_gpu),
        _ => false,
    }
}

fn parse_options(args: &[Value]) -> BuiltinResult<JsonEncodeOptions> {
    let mut options = JsonEncodeOptions::default();
    if args.is_empty() {
        return Ok(options);
    }

    if args.len() == 1 {
        if let Value::Struct(struct_value) = &args[0] {
            apply_struct_options(struct_value, &mut options)?;
            return Ok(options);
        }
        return Err(jsonencode_error(&JSONENCODE_ERROR_OPTIONS_CONFIG));
    }

    if !args.len().is_multiple_of(2) {
        return Err(jsonencode_error(&JSONENCODE_ERROR_NAME_VALUE_PAIRS));
    }

    let mut idx = 0usize;
    while idx < args.len() {
        let name = option_name(&args[idx])?;
        let value = &args[idx + 1];
        apply_option(&name, value, &mut options)?;
        idx += 2;
    }

    Ok(options)
}

fn apply_struct_options(
    struct_value: &StructValue,
    options: &mut JsonEncodeOptions,
) -> BuiltinResult<()> {
    for (key, value) in &struct_value.fields {
        apply_option(key, value, options)?;
    }
    Ok(())
}

fn option_name(value: &Value) -> BuiltinResult<String> {
    match value {
        Value::String(s) => Ok(s.clone()),
        Value::CharArray(ca) if ca.rows == 1 => Ok(ca.data.iter().collect()),
        Value::StringArray(sa) if sa.data.len() == 1 => Ok(sa.data[0].clone()),
        _ => Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_NAME)),
    }
}

fn apply_option(
    raw_name: &str,
    value: &Value,
    options: &mut JsonEncodeOptions,
) -> BuiltinResult<()> {
    let lowered = raw_name.to_ascii_lowercase();
    match lowered.as_str() {
        "prettyprint" => {
            options.pretty_print = coerce_bool(value)?;
            Ok(())
        }
        "convertinfandnan" => {
            options.convert_inf_and_nan = coerce_bool(value)?;
            Ok(())
        }
        other => Err(jsonencode_error_with(
            &JSONENCODE_ERROR_UNKNOWN_OPTION,
            format!("{} ('{}')", JSONENCODE_ERROR_UNKNOWN_OPTION.message, other),
        )),
    }
}

fn coerce_bool(value: &Value) -> BuiltinResult<bool> {
    match value {
        Value::Bool(b) => Ok(*b),
        Value::Int(i) => Ok(!i.is_zero()),
        Value::Num(n) => bool_from_f64(*n),
        Value::Tensor(t) => {
            if tensor::is_scalar_tensor(t) {
                if let Some(int) = t.integer_storage().and_then(|storage| storage.value_at(0)) {
                    return Ok(!int.is_zero());
                }
                bool_from_f64(tensor::tensor_value_f64(t, 0))
            } else {
                Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE))
            }
        }
        Value::LogicalArray(la) => match la.data.len() {
            1 => Ok(la.data[0] != 0),
            _ => Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE)),
        },
        Value::CharArray(ca) if ca.rows == 1 => {
            parse_bool_string(&ca.data.iter().collect::<String>())
        }
        Value::String(s) => parse_bool_string(s),
        Value::StringArray(sa) if sa.data.len() == 1 => parse_bool_string(&sa.data[0]),
        _ => Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE)),
    }
}

fn bool_from_f64(value: f64) -> BuiltinResult<bool> {
    if value.is_finite() {
        Ok(value != 0.0)
    } else {
        Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE))
    }
}

fn parse_bool_string(text: &str) -> BuiltinResult<bool> {
    match text.trim().to_ascii_lowercase().as_str() {
        "true" | "on" | "yes" | "1" => Ok(true),
        "false" | "off" | "no" | "0" => Ok(false),
        _ => Err(jsonencode_error(&JSONENCODE_ERROR_OPTION_VALUE)),
    }
}

fn value_to_json(value: &Value, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    match value {
        Value::Num(n) => number_to_json(*n, options),
        Value::Int(i) => Ok(JsonValue::Number(int_to_number(i))),
        Value::Bool(b) => Ok(JsonValue::Bool(*b)),
        Value::LogicalArray(logical) => logical_array_to_json(logical, options),
        Value::Tensor(tensor) => tensor_to_json(tensor, options),
        Value::SparseTensor(sparse) => {
            let total_elements = sparse.rows.checked_mul(sparse.cols).ok_or_else(|| {
                jsonencode_error_with(
                    &JSONENCODE_ERROR_INTERNAL,
                    "jsonencode: sparse matrix dimensions overflow",
                )
            })?;
            if total_elements > 10_000_000 {
                return Err(jsonencode_error_with(
                    &JSONENCODE_ERROR_INTERNAL,
                    format!("jsonencode: cannot densify sparse tensor {}x{} ({} elements exceeds safe threshold)", sparse.rows, sparse.cols, total_elements),
                ));
            }
            if sparse.is_logical() {
                let dense = sparse.to_dense_logical().map_err(|err| {
                    jsonencode_error_with(&JSONENCODE_ERROR_INTERNAL, format!("jsonencode: {err}"))
                })?;
                return logical_array_to_json(&dense, options);
            }
            let dense = sparse.to_dense().map_err(|err| {
                jsonencode_error_with(&JSONENCODE_ERROR_INTERNAL, format!("jsonencode: {err}"))
            })?;
            tensor_to_json(&dense, options)
        }
        Value::Complex(re, im) => complex_scalar_to_json(*re, *im, options),
        Value::ComplexTensor(ct) => complex_tensor_to_json(ct, options),
        Value::String(s) => Ok(JsonValue::String(s.clone())),
        Value::Symbolic(expr) => Ok(JsonValue::String(expr.to_string())),
        Value::SymbolicArray(array) => symbolic_array_to_json(array, options),
        Value::StringArray(sa) => string_array_to_json(sa, options),
        Value::CharArray(ca) => char_array_to_json(ca, options),
        Value::Struct(sv) => struct_to_json(sv, options),
        Value::Cell(ca) => cell_array_to_json(ca, options),
        Value::ObjectArray(array) => array
            .data()
            .iter()
            .map(|value| value_to_json(value, options))
            .collect::<BuiltinResult<Vec<_>>>()
            .map(JsonValue::Array),
        Value::Object(obj) => object_to_json(obj, options),
        Value::GpuTensor(_) => Err(jsonencode_error(&JSONENCODE_ERROR_UNEXPECTED_GPU)),
        Value::HandleObject(_)
        | Value::Listener(_)
        | Value::FunctionHandle(_)
        | Value::ExternalFunctionHandle(_)
        | Value::MethodFunctionHandle(_)
        | Value::BoundFunctionHandle { .. }
        | Value::Closure(_)
        | Value::ClassRef(_)
        | Value::MException(_)
        | Value::Future(_)
        | Value::Task(_)
        | Value::Pool(_)
        | Value::Job(_)
        | Value::Foreign(_)
        | Value::OutputList(_) => Err(jsonencode_error(&JSONENCODE_ERROR_UNSUPPORTED_TYPE)),
    }
}

fn int_to_number(value: &IntValue) -> JsonNumber {
    match value {
        IntValue::I8(v) => JsonNumber::I64(*v as i64),
        IntValue::I16(v) => JsonNumber::I64(*v as i64),
        IntValue::I32(v) => JsonNumber::I64(*v as i64),
        IntValue::I64(v) => JsonNumber::I64(*v),
        IntValue::U8(v) => JsonNumber::U64(*v as u64),
        IntValue::U16(v) => JsonNumber::U64(*v as u64),
        IntValue::U32(v) => JsonNumber::U64(*v as u64),
        IntValue::U64(v) => JsonNumber::U64(*v),
    }
}

fn number_to_json(value: f64, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    if !value.is_finite() {
        if options.convert_inf_and_nan {
            return Ok(JsonValue::Null);
        }
        return Err(jsonencode_error(&JSONENCODE_ERROR_INF_NAN));
    }
    Ok(JsonValue::Number(JsonNumber::Float(value)))
}

fn logical_array_to_json(
    logical: &LogicalArray,
    _options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    let keep_dims = compute_keep_dims(&logical.shape, true);
    if logical.shape.is_empty() || logical.data.is_empty() {
        return Ok(JsonValue::Array(Vec::new()));
    }
    if keep_dims.is_empty() {
        let first = logical.data.first().copied().unwrap_or(0) != 0;
        return Ok(JsonValue::Bool(first));
    }
    build_strided_array(&logical.shape, &keep_dims, |offset| {
        Ok(JsonValue::Bool(logical.data[offset] != 0))
    })
}

fn tensor_to_json(tensor: &Tensor, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    if tensor::tensor_element_len(tensor) == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let keep_dims = compute_keep_dims(&tensor.shape, true);
    if keep_dims.is_empty() {
        return tensor_value_to_json(tensor, 0, options);
    }
    build_strided_array(&tensor.shape, &keep_dims, |offset| {
        tensor_value_to_json(tensor, offset, options)
    })
}

fn tensor_value_to_json(
    tensor: &Tensor,
    offset: usize,
    options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    let value = tensor
        .numeric_value_at(offset)
        .expect("index within authoritative numeric storage");
    match value.into_int_value() {
        Some(value) => Ok(JsonValue::Number(integer_value_number(&value))),
        None => number_to_json(value.materialize_f64(), options),
    }
}

fn integer_value_number(value: &IntValue) -> JsonNumber {
    match value {
        IntValue::I8(value) => JsonNumber::I64(*value as i64),
        IntValue::I16(value) => JsonNumber::I64(*value as i64),
        IntValue::I32(value) => JsonNumber::I64(*value as i64),
        IntValue::I64(value) => JsonNumber::I64(*value),
        IntValue::U8(value) => JsonNumber::U64(*value as u64),
        IntValue::U16(value) => JsonNumber::U64(*value as u64),
        IntValue::U32(value) => JsonNumber::U64(*value as u64),
        IntValue::U64(value) => JsonNumber::U64(*value),
    }
}

fn integer_storage_number(storage: &IntegerStorage, offset: usize) -> JsonNumber {
    integer_value_number(
        &storage
            .value_at(offset)
            .expect("index within authoritative integer storage"),
    )
}

fn complex_scalar_to_json(
    real: f64,
    imag: f64,
    options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    let real_json = number_to_json(real, options)?;
    let imag_json = number_to_json(imag, options)?;
    Ok(JsonValue::Object(vec![
        ("real".to_string(), real_json),
        ("imag".to_string(), imag_json),
    ]))
}

fn complex_tensor_to_json(
    ct: &ComplexTensor,
    options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    if tensor::complex_tensor_element_len(ct) == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let keep_dims = compute_keep_dims(&ct.shape, true);
    if keep_dims.is_empty() {
        return complex_tensor_value_to_json(ct, 0, options);
    }
    build_strided_array(&ct.shape, &keep_dims, |offset| {
        complex_tensor_value_to_json(ct, offset, options)
    })
}

fn complex_tensor_value_to_json(
    ct: &ComplexTensor,
    offset: usize,
    options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    if let Some(storage) = &ct.integer_storage() {
        return Ok(JsonValue::Object(vec![
            (
                "real".to_string(),
                JsonValue::Number(integer_storage_number(&storage.real, offset)),
            ),
            (
                "imag".to_string(),
                JsonValue::Number(integer_storage_number(&storage.imag, offset)),
            ),
        ]));
    }

    let (real, imag) = ct.materialize_f64()[offset];
    complex_scalar_to_json(real, imag, options)
}

fn string_array_to_json(
    sa: &StringArray,
    _options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    if sa.data.is_empty() {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let keep_dims = compute_keep_dims(&sa.shape, true);
    if keep_dims.is_empty() {
        return Ok(JsonValue::String(sa.data[0].clone()));
    }
    build_strided_array(&sa.shape, &keep_dims, |offset| {
        Ok(JsonValue::String(sa.data[offset].clone()))
    })
}

fn symbolic_array_to_json(
    array: &SymbolicArray,
    _options: &JsonEncodeOptions,
) -> BuiltinResult<JsonValue> {
    if array.data.is_empty() {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let keep_dims = compute_keep_dims(&array.shape, true);
    if keep_dims.is_empty() {
        return Ok(JsonValue::String(array.data[0].to_string()));
    }
    build_strided_array(&array.shape, &keep_dims, |offset| {
        Ok(JsonValue::String(array.data[offset].to_string()))
    })
}

fn char_array_to_json(ca: &CharArray, _options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    if ca.rows == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }

    if ca.cols == 0 {
        if ca.rows == 1 {
            return Ok(JsonValue::String(String::new()));
        }
        let mut rows = Vec::with_capacity(ca.rows);
        for _ in 0..ca.rows {
            rows.push(JsonValue::String(String::new()));
        }
        return Ok(JsonValue::Array(rows));
    }

    if ca.rows == 1 {
        return Ok(JsonValue::String(ca.data.iter().collect()));
    }

    let mut rows = Vec::with_capacity(ca.rows);
    for r in 0..ca.rows {
        let mut row_string = String::with_capacity(ca.cols);
        for c in 0..ca.cols {
            row_string.push(ca.data[r * ca.cols + c]);
        }
        rows.push(JsonValue::String(row_string));
    }
    Ok(JsonValue::Array(rows))
}

fn struct_to_json(sv: &StructValue, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    if sv.fields.is_empty() {
        return Ok(JsonValue::Object(Vec::new()));
    }
    let mut map = BTreeMap::new();
    for (key, value) in &sv.fields {
        map.insert(key.clone(), value_to_json(value, options)?);
    }
    Ok(JsonValue::Object(map.into_iter().collect()))
}

fn object_to_json(obj: &ObjectInstance, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    let mut map = BTreeMap::new();
    for (key, value) in &obj.properties {
        map.insert(key.clone(), value_to_json(value, options)?);
    }
    Ok(JsonValue::Object(map.into_iter().collect()))
}

fn cell_array_to_json(ca: &CellArray, options: &JsonEncodeOptions) -> BuiltinResult<JsonValue> {
    if ca.rows == 0 || ca.cols == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }

    if ca.rows == 1 && ca.cols == 1 {
        let value = ca.get(0, 0).map_err(|e| {
            jsonencode_error_with(
                &JSONENCODE_ERROR_INTERNAL,
                format!("{} ({e})", JSONENCODE_ERROR_INTERNAL.message),
            )
        })?;
        return Ok(JsonValue::Array(vec![value_to_json(&value, options)?]));
    }

    if ca.rows == 1 {
        let mut row = Vec::with_capacity(ca.cols);
        for c in 0..ca.cols {
            let element = ca.get(0, c).map_err(|e| {
                jsonencode_error_with(
                    &JSONENCODE_ERROR_INTERNAL,
                    format!("{} ({e})", JSONENCODE_ERROR_INTERNAL.message),
                )
            })?;
            row.push(value_to_json(&element, options)?);
        }
        return Ok(JsonValue::Array(row));
    }

    if ca.cols == 1 {
        let mut column = Vec::with_capacity(ca.rows);
        for r in 0..ca.rows {
            let element = ca.get(r, 0).map_err(|e| {
                jsonencode_error_with(
                    &JSONENCODE_ERROR_INTERNAL,
                    format!("{} ({e})", JSONENCODE_ERROR_INTERNAL.message),
                )
            })?;
            column.push(value_to_json(&element, options)?);
        }
        return Ok(JsonValue::Array(column));
    }

    let mut rows = Vec::with_capacity(ca.rows);
    for r in 0..ca.rows {
        let mut row = Vec::with_capacity(ca.cols);
        for c in 0..ca.cols {
            let element = ca.get(r, c).map_err(|e| {
                jsonencode_error_with(
                    &JSONENCODE_ERROR_INTERNAL,
                    format!("{} ({e})", JSONENCODE_ERROR_INTERNAL.message),
                )
            })?;
            row.push(value_to_json(&element, options)?);
        }
        rows.push(JsonValue::Array(row));
    }
    Ok(JsonValue::Array(rows))
}

fn compute_keep_dims(shape: &[usize], drop_singletons: bool) -> Vec<usize> {
    let mut keep = Vec::new();
    for (idx, &size) in shape.iter().enumerate() {
        if size != 1 || !drop_singletons {
            keep.push(idx);
        }
    }
    keep
}

fn compute_strides(shape: &[usize]) -> Vec<usize> {
    let mut strides = Vec::with_capacity(shape.len());
    let mut acc = 1usize;
    for &size in shape {
        strides.push(acc);
        acc = acc.saturating_mul(size.max(1));
    }
    strides
}

fn build_strided_array<F>(
    shape: &[usize],
    keep_dims: &[usize],
    mut fetch: F,
) -> BuiltinResult<JsonValue>
where
    F: FnMut(usize) -> BuiltinResult<JsonValue>,
{
    if keep_dims.is_empty() {
        return fetch(0);
    }
    if keep_dims.iter().any(|&idx| shape[idx] == 0) {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let strides = compute_strides(shape);
    let dims: Vec<usize> = keep_dims.iter().map(|&idx| shape[idx]).collect();
    build_nd_array(&dims, |indices| {
        let mut offset = 0usize;
        for (value, dim_idx) in indices.iter().zip(keep_dims.iter()) {
            offset += value * strides[*dim_idx];
        }
        fetch(offset)
    })
}

fn build_nd_array<F>(dims: &[usize], mut fetch: F) -> BuiltinResult<JsonValue>
where
    F: FnMut(&[usize]) -> BuiltinResult<JsonValue>,
{
    if dims.is_empty() {
        return fetch(&[]);
    }
    if dims[0] == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }
    let mut indices = vec![0usize; dims.len()];
    build_nd_array_recursive(dims, 0, &mut indices, &mut fetch)
}

fn build_nd_array_recursive<F>(
    dims: &[usize],
    level: usize,
    indices: &mut [usize],
    fetch: &mut F,
) -> BuiltinResult<JsonValue>
where
    F: FnMut(&[usize]) -> BuiltinResult<JsonValue>,
{
    let size = dims[level];
    if size == 0 {
        return Ok(JsonValue::Array(Vec::new()));
    }
    if level + 1 == dims.len() {
        let mut items = Vec::with_capacity(size);
        for i in 0..size {
            indices[level] = i;
            items.push(fetch(indices)?);
        }
        return Ok(JsonValue::Array(items));
    }
    let mut items = Vec::with_capacity(size);
    for i in 0..size {
        indices[level] = i;
        items.push(build_nd_array_recursive(dims, level + 1, indices, fetch)?);
    }
    Ok(JsonValue::Array(items))
}

fn render_json(value: &JsonValue, options: &JsonEncodeOptions) -> String {
    let mut writer = JsonWriter::new(options.pretty_print);
    writer.write_value(value);
    writer.finish()
}

struct JsonWriter {
    output: String,
    pretty: bool,
    indent: usize,
}

impl JsonWriter {
    fn new(pretty: bool) -> Self {
        Self {
            output: String::new(),
            pretty,
            indent: 0,
        }
    }

    fn finish(self) -> String {
        self.output
    }

    fn write_value(&mut self, value: &JsonValue) {
        match value {
            JsonValue::Null => self.output.push_str("null"),
            JsonValue::Bool(true) => self.output.push_str("true"),
            JsonValue::Bool(false) => self.output.push_str("false"),
            JsonValue::Number(number) => self.write_number(number),
            JsonValue::String(text) => {
                self.output.push('"');
                self.output.push_str(&escape_json_string(text));
                self.output.push('"');
            }
            JsonValue::Array(items) => self.write_array(items),
            JsonValue::Object(fields) => self.write_object(fields),
        }
    }

    fn write_number(&mut self, number: &JsonNumber) {
        match number {
            JsonNumber::Float(f) => {
                if f.is_nan() || !f.is_finite() {
                    self.output.push_str("null");
                } else {
                    self.output.push_str(&format_number(*f));
                }
            }
            JsonNumber::I64(i) => {
                let _ = write!(self.output, "{i}");
            }
            JsonNumber::U64(u) => {
                let _ = write!(self.output, "{u}");
            }
        }
    }

    fn write_array(&mut self, items: &[JsonValue]) {
        if items.is_empty() {
            self.output.push_str("[]");
            return;
        }
        let inline = if self.pretty {
            items.iter().all(|item| {
                matches!(
                    item,
                    JsonValue::Null
                        | JsonValue::Bool(_)
                        | JsonValue::Number(_)
                        | JsonValue::String(_)
                )
            })
        } else {
            false
        };
        if inline {
            self.output.push('[');
            for (index, item) in items.iter().enumerate() {
                self.write_value(item);
                if index + 1 < items.len() {
                    self.output.push(',');
                }
            }
            self.output.push(']');
            return;
        }
        self.output.push('[');
        if self.pretty {
            self.output.push('\n');
            self.indent += 1;
        }
        for (index, item) in items.iter().enumerate() {
            if self.pretty {
                self.write_indent();
            }
            self.write_value(item);
            if index + 1 < items.len() {
                if self.pretty {
                    self.output.push_str(",\n");
                } else {
                    self.output.push(',');
                }
            }
        }
        if self.pretty {
            self.output.push('\n');
            if self.indent > 0 {
                self.indent -= 1;
            }
            self.write_indent();
        }
        self.output.push(']');
    }

    fn write_object(&mut self, fields: &[(String, JsonValue)]) {
        if fields.is_empty() {
            self.output.push_str("{}");
            return;
        }
        self.output.push('{');
        if self.pretty {
            self.output.push('\n');
            self.indent += 1;
        }
        for (index, (key, value)) in fields.iter().enumerate() {
            if self.pretty {
                self.write_indent();
            }
            self.output.push('"');
            self.output.push_str(&escape_json_string(key));
            self.output.push('"');
            if self.pretty {
                self.output.push_str(": ");
            } else {
                self.output.push(':');
            }
            self.write_value(value);
            if index + 1 < fields.len() {
                if self.pretty {
                    self.output.push_str(",\n");
                } else {
                    self.output.push(',');
                }
            }
        }
        if self.pretty {
            self.output.push('\n');
            if self.indent > 0 {
                self.indent -= 1;
            }
            self.write_indent();
        }
        self.output.push('}');
    }

    fn write_indent(&mut self) {
        if self.pretty {
            for _ in 0..self.indent {
                self.output.push_str("    ");
            }
        }
    }
}

fn escape_json_string(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '"' => escaped.push_str("\\\""),
            '\\' => escaped.push_str("\\\\"),
            '\u{08}' => escaped.push_str("\\b"),
            '\u{0C}' => escaped.push_str("\\f"),
            '\n' => escaped.push_str("\\n"),
            '\r' => escaped.push_str("\\r"),
            '\t' => escaped.push_str("\\t"),
            c if (c as u32) < 0x20 => {
                let _ = write!(escaped, "\\u{:04X}", c as u32);
            }
            _ => escaped.push(ch),
        }
    }
    escaped
}

fn format_number(value: f64) -> String {
    if value.fract() == 0.0 {
        // Display integer-like doubles without decimal point
        format!("{:.0}", value)
    } else {
        format!("{}", value)
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use crate::builtins::common::test_support;
    use futures::executor::block_on;
    use runmat_value::{
        CellArray, CharArray, ComplexTensor, LogicalArray, StringArray, StructValue, SymbolicArray,
        SymbolicExpr, Tensor,
    };

    fn as_string(value: Value) -> String {
        match value {
            Value::CharArray(ca) => ca.data.iter().collect(),
            Value::String(s) => s,
            other => panic!("expected char array, got {:?}", other),
        }
    }

    fn error_message(err: crate::RuntimeError) -> String {
        err.message().to_string()
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_descriptor_signatures_cover_core_forms() {
        let labels: Vec<&str> = JSONENCODE_DESCRIPTOR
            .signatures
            .iter()
            .map(|sig| sig.label)
            .collect();
        assert!(labels.contains(&"jsonText = jsonencode(value)"));
        assert!(labels.contains(&"jsonText = jsonencode(value, options)"));
        assert!(labels.contains(&"jsonText = jsonencode(value, name, optionValue)"));
        assert!(labels.contains(&"jsonText = jsonencode(value, nameValuePairs...)"));
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_scalar_double() {
        let encoded =
            block_on(jsonencode_builtin(Value::Num(5.0), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "5");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_symbolic_value_as_text() {
        let expr = SymbolicExpr::div_expr(
            SymbolicExpr::function(
                runmat_value::SymbolicFunction::Sin,
                SymbolicExpr::variable("x"),
            ),
            SymbolicExpr::variable("x"),
        );
        let encoded =
            block_on(jsonencode_builtin(Value::Symbolic(expr), Vec::new())).expect("jsonencode");

        assert_eq!(as_string(encoded), "\"sin(x)/x\"");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_symbolic_array_preserves_matrix_shape() {
        let array = SymbolicArray::new(
            vec![
                SymbolicExpr::variable("a"),
                SymbolicExpr::variable("c"),
                SymbolicExpr::variable("b"),
                SymbolicExpr::variable("d"),
            ],
            vec![2, 2],
        )
        .expect("symbolic array");

        let encoded = block_on(jsonencode_builtin(Value::SymbolicArray(array), Vec::new()))
            .expect("jsonencode");

        assert_eq!(as_string(encoded), "[[\"a\",\"b\"],[\"c\",\"d\"]]");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_matrix_pretty_print() {
        let tensor = Tensor::new(vec![1.0, 4.0, 2.0, 5.0, 3.0, 6.0], vec![2, 3]).expect("tensor");
        let args = vec![Value::from("PrettyPrint"), Value::Bool(true)];
        let encoded =
            block_on(jsonencode_builtin(Value::Tensor(tensor), args)).expect("jsonencode");
        let expected = "[\n    [1,2,3],\n    [4,5,6]\n]";
        assert_eq!(as_string(encoded), expected);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_integer_tensor_preserves_exact_uint64_values() {
        let tensor =
            Tensor::new_integer(IntegerStorage::U64(vec![u64::MAX, 1_u64 << 63]), vec![1, 2])
                .expect("integer tensor");

        let encoded =
            block_on(jsonencode_builtin(Value::Tensor(tensor), Vec::new())).expect("jsonencode");

        assert_eq!(
            as_string(encoded),
            format!("[{},{}]", u64::MAX, 1_u64 << 63)
        );
    }

    #[test]
    fn jsonencode_integer_tensor_serializes_all_eight_classes_exactly() {
        let cases = [
            (IntegerStorage::I8(vec![i8::MIN]), "-128"),
            (IntegerStorage::I16(vec![i16::MIN]), "-32768"),
            (IntegerStorage::I32(vec![i32::MIN]), "-2147483648"),
            (IntegerStorage::I64(vec![i64::MIN]), "-9223372036854775808"),
            (IntegerStorage::U8(vec![u8::MAX]), "255"),
            (IntegerStorage::U16(vec![u16::MAX]), "65535"),
            (IntegerStorage::U32(vec![u32::MAX]), "4294967295"),
            (IntegerStorage::U64(vec![u64::MAX]), "18446744073709551615"),
        ];
        for (storage, expected) in cases {
            let tensor = Tensor::new_integer(storage, vec![1, 1]).expect("integer tensor");
            let encoded = block_on(jsonencode_builtin(Value::Tensor(tensor), Vec::new()))
                .expect("jsonencode integer tensor");
            assert_eq!(as_string(encoded), expected);
        }
    }

    #[test]
    fn jsonencode_real_integer_payload_remains_public_and_exact_in_strict_mode() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let cases = [
            (Value::Int(IntValue::I8(i8::MIN)), "-128"),
            (Value::Int(IntValue::I16(i16::MIN)), "-32768"),
            (Value::Int(IntValue::I32(i32::MIN)), "-2147483648"),
            (Value::Int(IntValue::I64(i64::MIN)), "-9223372036854775808"),
            (Value::Int(IntValue::U8(u8::MAX)), "255"),
            (Value::Int(IntValue::U16(u16::MAX)), "65535"),
            (Value::Int(IntValue::U32(u32::MAX)), "4294967295"),
            (Value::Int(IntValue::U64(u64::MAX)), "18446744073709551615"),
        ];
        for (value, expected) in cases {
            let encoded = block_on(jsonencode_builtin(value, Vec::new()))
                .expect("documented real integer payload");
            assert_eq!(as_string(encoded), expected);
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_struct_round_trip() {
        let mut fields = StructValue::new();
        fields
            .fields
            .insert("name".to_string(), Value::from("RunMat"));
        fields
            .fields
            .insert("year".to_string(), Value::Int(IntValue::I32(2025)));
        let encoded =
            block_on(jsonencode_builtin(Value::Struct(fields), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "{\"name\":\"RunMat\",\"year\":2025}");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_struct_options_enable_pretty_print() {
        let tensor = Tensor::new(vec![1.0, 4.0, 2.0, 5.0], vec![2, 2]).expect("tensor");
        let mut opts = StructValue::new();
        opts.fields
            .insert("PrettyPrint".to_string(), Value::Bool(true));
        let encoded = block_on(jsonencode_builtin(
            Value::Tensor(tensor),
            vec![Value::Struct(opts)],
        ))
        .expect("jsonencode");
        let expected = "[\n    [1,2],\n    [4,5]\n]";
        assert_eq!(as_string(encoded), expected);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_options_accept_scalar_tensor_bool() {
        let _runmat = crate::compatibility::push_runmat_extensions_enabled(true);
        let tensor_value = Tensor::new(vec![1.0], vec![1, 1]).expect("tensor");
        let args = vec![Value::from("PrettyPrint"), Value::Tensor(tensor_value)];
        let encoded = block_on(jsonencode_builtin(Value::Num(42.0), args)).expect("jsonencode");
        assert_eq!(as_string(encoded), "42");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_options_read_wide_uint64_storage_exactly() {
        let _runmat = crate::compatibility::push_runmat_extensions_enabled(true);
        let false_option =
            Tensor::new_integer(IntegerStorage::U8(vec![0]), vec![1, 1]).expect("integer tensor");
        let compact = block_on(jsonencode_builtin(
            Value::Tensor(Tensor::new(vec![1.0, 2.0], vec![1, 2]).expect("tensor")),
            vec![Value::from("PrettyPrint"), Value::Tensor(false_option)],
        ))
        .expect("jsonencode");
        assert_eq!(as_string(compact), "[1,2]");

        let true_option = Tensor::new_integer(IntegerStorage::U64(vec![u64::MAX]), vec![1, 1])
            .expect("integer tensor");
        let pretty = block_on(jsonencode_builtin(
            Value::Tensor(Tensor::new(vec![1.0, 3.0, 2.0, 4.0], vec![2, 2]).expect("tensor")),
            vec![Value::from("PrettyPrint"), Value::Tensor(true_option)],
        ))
        .expect("jsonencode");
        assert_eq!(as_string(pretty), "[\n    [1,2],\n    [3,4]\n]");
    }

    #[test]
    fn jsonencode_option_coercions_are_independently_gated() {
        let cases = [
            (
                Value::Int(IntValue::U64(u64::MAX)),
                JSONENCODE_TYPED_INTEGER_OPTION_EXTENSION.error_identifier,
            ),
            (
                Value::Num(1.0),
                JSONENCODE_NUMERIC_OPTION_EXTENSION.error_identifier,
            ),
            (
                Value::from("true"),
                JSONENCODE_TEXT_OPTION_EXTENSION.error_identifier,
            ),
        ];
        for (option, expected_identifier) in cases {
            let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
            let error = block_on(jsonencode_builtin(
                Value::Num(1.0),
                vec![Value::from("PrettyPrint"), option],
            ))
            .expect_err("option coercion must be gated");
            assert_eq!(error.identifier(), expected_identifier);
        }
    }

    #[test]
    fn jsonencode_documented_convert_inf_numeric_bool_remains_public() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let encoded = block_on(jsonencode_builtin(
            Value::Num(1.0),
            vec![Value::from("ConvertInfAndNaN"), Value::Num(1.0)],
        ))
        .expect("documented numeric one");
        assert_eq!(as_string(encoded), "1");

        let error = block_on(jsonencode_builtin(
            Value::Num(f64::NAN),
            vec![Value::from("ConvertInfAndNaN"), Value::Num(0.0)],
        ))
        .expect_err("documented numeric zero disables conversion");
        assert_eq!(error.message(), JSONENCODE_ERROR_INF_NAN.message);
    }

    #[test]
    fn jsonencode_option_errors_precede_irrelevant_extension_gates() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let unknown = block_on(jsonencode_builtin(
            Value::Num(1.0),
            vec![Value::from("Unknown"), Value::Num(1.0)],
        ))
        .expect_err("unknown name must reject before numeric coercion gate");
        assert!(unknown
            .message()
            .starts_with(JSONENCODE_ERROR_UNKNOWN_OPTION.message));

        let nonscalar = Tensor::new(vec![1.0, 0.0], vec![1, 2]).expect("tensor");
        let invalid = block_on(jsonencode_builtin(
            Value::Num(1.0),
            vec![Value::from("PrettyPrint"), Value::Tensor(nonscalar)],
        ))
        .expect_err("nonscalar value must reject before numeric coercion gate");
        assert_eq!(invalid.message(), JSONENCODE_ERROR_OPTION_VALUE.message);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_options_reject_non_scalar_tensor_bool() {
        let tensor = Tensor::new(vec![1.0, 0.0], vec![1, 2]).expect("tensor");
        let err = block_on(jsonencode_builtin(
            Value::Num(1.0),
            vec![Value::from("PrettyPrint"), Value::Tensor(tensor)],
        ))
        .expect_err("expected failure");
        assert_eq!(error_message(err), JSONENCODE_ERROR_OPTION_VALUE.message);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_options_accept_scalar_logical_array() {
        let logical = LogicalArray::new(vec![1], vec![1]).expect("logical");
        let args = vec![Value::from("PrettyPrint"), Value::LogicalArray(logical)];
        let encoded = block_on(jsonencode_builtin(Value::Num(7.0), args)).expect("jsonencode");
        assert_eq!(as_string(encoded), "7");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_convert_inf_and_nan_controls_null_output() {
        let tensor = Tensor::new(vec![1.0, f64::NAN], vec![1, 2]).expect("tensor");
        let encoded = block_on(jsonencode_builtin(
            Value::Tensor(tensor.clone()),
            Vec::new(),
        ))
        .expect("jsonencode");
        assert_eq!(as_string(encoded), "[1,null]");

        let err = block_on(jsonencode_builtin(
            Value::Tensor(tensor),
            vec![Value::from("ConvertInfAndNaN"), Value::Bool(false)],
        ))
        .expect_err("expected failure");
        assert_eq!(error_message(err), JSONENCODE_ERROR_INF_NAN.message);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_cell_array() {
        let elements = vec![Value::from(1.0), Value::from("two")];
        let cell = CellArray::new(elements, 1, 2).expect("cell");
        let encoded =
            block_on(jsonencode_builtin(Value::Cell(cell), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "[1,\"two\"]");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_char_array_zero_rows_is_empty_array() {
        let chars = CharArray::new(Vec::new(), 0, 3).expect("char array");
        let encoded =
            block_on(jsonencode_builtin(Value::CharArray(chars), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "[]");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_char_array_empty_strings_per_row() {
        let chars = CharArray::new(Vec::new(), 2, 0).expect("char array");
        let encoded =
            block_on(jsonencode_builtin(Value::CharArray(chars), Vec::new())).expect("jsonencode");
        let encoded_str = as_string(encoded);
        assert_eq!(encoded_str, "[\"\",\"\"]");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_string_array_matrix() {
        let sa = StringArray::new(vec!["alpha".to_string(), "beta".to_string()], vec![2, 1])
            .expect("string array");
        let encoded =
            block_on(jsonencode_builtin(Value::StringArray(sa), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "[\"alpha\",\"beta\"]");
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_complex_tensor_outputs_objects() {
        let _runmat = crate::compatibility::push_runmat_extensions_enabled(true);
        let ct = ComplexTensor::new(vec![(1.0, 2.0), (3.5, -4.0)], vec![2, 1]).expect("complex");
        let encoded =
            block_on(jsonencode_builtin(Value::ComplexTensor(ct), Vec::new())).expect("jsonencode");
        assert_eq!(
            as_string(encoded),
            "[{\"real\":1,\"imag\":2},{\"real\":3.5,\"imag\":-4}]"
        );
    }

    #[test]
    fn jsonencode_typed_complex_integers_preserves_every_class_exactly() {
        let _runmat = crate::compatibility::push_runmat_extensions_enabled(true);
        let cases = [
            (
                "int8",
                IntegerStorage::I8(vec![-1]),
                IntegerStorage::I8(vec![2]),
                "{\"real\":-1,\"imag\":2}",
            ),
            (
                "int16",
                IntegerStorage::I16(vec![-3]),
                IntegerStorage::I16(vec![4]),
                "{\"real\":-3,\"imag\":4}",
            ),
            (
                "int32",
                IntegerStorage::I32(vec![-5]),
                IntegerStorage::I32(vec![6]),
                "{\"real\":-5,\"imag\":6}",
            ),
            (
                "int64",
                IntegerStorage::I64(vec![-9223372036854775808]),
                IntegerStorage::I64(vec![9223372036854775807]),
                "{\"real\":-9223372036854775808,\"imag\":9223372036854775807}",
            ),
            (
                "uint8",
                IntegerStorage::U8(vec![1]),
                IntegerStorage::U8(vec![2]),
                "{\"real\":1,\"imag\":2}",
            ),
            (
                "uint16",
                IntegerStorage::U16(vec![3]),
                IntegerStorage::U16(vec![4]),
                "{\"real\":3,\"imag\":4}",
            ),
            (
                "uint32",
                IntegerStorage::U32(vec![5]),
                IntegerStorage::U32(vec![6]),
                "{\"real\":5,\"imag\":6}",
            ),
            (
                "uint64",
                IntegerStorage::U64(vec![u64::MAX]),
                IntegerStorage::U64(vec![1_u64 << 63]),
                "{\"real\":18446744073709551615,\"imag\":9223372036854775808}",
            ),
        ];

        for (class, real, imag, expected) in cases {
            let storage = runmat_value::IntegerComplexStorage::new(real, imag)
                .expect("matching integer components");
            let tensor = ComplexTensor::new_integer(storage, vec![1, 1]).expect("typed complex");
            let encoded = block_on(jsonencode_builtin(Value::ComplexTensor(tensor), Vec::new()))
                .expect("jsonencode typed complex integer");
            assert_eq!(as_string(encoded), expected, "{class}");
        }
    }

    #[test]
    fn jsonencode_complex_input_is_rejected_by_compatibility_gate() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let error = block_on(jsonencode_builtin(Value::Complex(1.0, 2.0), Vec::new()))
            .expect_err("complex encoding is a RunMat extension");
        assert_eq!(
            error.identifier(),
            JSONENCODE_COMPLEX_INPUT_EXTENSION.error_identifier
        );
    }

    #[test]
    fn jsonencode_nested_complex_and_sparse_inputs_are_compatibility_gated() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let complex_cell = CellArray::new(vec![Value::Complex(1.0, 2.0)], 1, 1).expect("cell");
        let complex_error = block_on(jsonencode_builtin(Value::Cell(complex_cell), Vec::new()))
            .expect_err("nested complex input is an extension");
        assert_eq!(
            complex_error.identifier(),
            JSONENCODE_COMPLEX_INPUT_EXTENSION.error_identifier
        );

        let sparse =
            runmat_value::SparseTensor::new(1, 1, vec![0, 1], vec![0], vec![1.0]).expect("sparse");
        let mut fields = StructValue::new();
        fields
            .fields
            .insert("value".to_string(), Value::SparseTensor(sparse));
        let sparse_error = block_on(jsonencode_builtin(Value::Struct(fields), Vec::new()))
            .expect_err("nested sparse input is an extension");
        assert_eq!(
            sparse_error.identifier(),
            JSONENCODE_SPARSE_INPUT_EXTENSION.error_identifier
        );
    }

    #[test]
    fn jsonencode_resident_gate_precedes_provider_access() {
        let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
        let handle = runmat_accelerate_api::GpuTensorHandle {
            shape: vec![1, 1],
            device_id: u32::MAX,
            buffer_id: u64::MAX,
            descriptor: Default::default(),
        };
        let handle = handle.with_provenance(runmat_accelerate_api::GpuHandleProvenance::Explicit);
        let error = block_on(jsonencode_builtin(
            Value::GpuTensor(handle.clone()),
            Vec::new(),
        ))
        .expect_err("resident extension must gate before owner lookup");
        runmat_accelerate_api::clear_handle_metadata(&handle);
        assert_eq!(
            error.identifier(),
            JSONENCODE_RESIDENT_INPUT_EXTENSION.error_identifier
        );
    }

    #[test]
    fn jsonencode_integer_metadata_distinguishes_public_real_and_extended_complex() {
        assert_eq!(JSONENCODE_INTEGER_CAPABILITIES.len(), 3);
        assert_eq!(
            JSONENCODE_INTEGER_CAPABILITIES[0].inputs[0].availability,
            BuiltinIntegerInputAvailability::Documented
        );
        assert_eq!(
            JSONENCODE_INTEGER_CAPABILITIES[1].inputs[0].availability,
            BuiltinIntegerInputAvailability::RunMatOnly
        );
        assert_eq!(
            JSONENCODE_INTEGER_CAPABILITIES[2].inputs[0].availability,
            BuiltinIntegerInputAvailability::RunMatOnly
        );
        assert_eq!(JSONENCODE_EXTENSIONS.len(), 6);
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn jsonencode_gpu_tensor_gathers_host_data() {
        test_support::with_test_provider(|provider| {
            let _strict = crate::compatibility::push_runmat_extensions_enabled(false);
            let tensor = Tensor::new(vec![1.0, 0.0, 0.0, 1.0], vec![2, 2]).expect("tensor");
            let view = runmat_accelerate_api::HostTensorView {
                data: &tensor.materialize_f64(),
                shape: &tensor.shape,
            };
            let handle = provider.upload(&view).expect("upload");
            let encoded = block_on(jsonencode_builtin(Value::GpuTensor(handle), Vec::new()))
                .expect("jsonencode");
            assert_eq!(as_string(encoded), "[[1,0],[0,1]]");
        });
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    #[cfg(feature = "wgpu")]
    fn jsonencode_gpu_tensor_wgpu_gathers_host_data() {
        let ensure = runmat_accelerate::backend::wgpu::provider::ensure_wgpu_provider();
        let Some(_) = ensure.ok().flatten() else {
            // No WGPU device available on this host; skip.
            return;
        };
        let provider = runmat_accelerate_api::provider().expect("wgpu provider");
        let tensor = Tensor::new(vec![1.0, 2.0, 3.0], vec![3, 1]).expect("tensor");
        let view = runmat_accelerate_api::HostTensorView {
            data: &tensor.materialize_f64(),
            shape: &tensor.shape,
        };
        let handle = provider.upload(&view).expect("upload");
        let encoded =
            block_on(jsonencode_builtin(Value::GpuTensor(handle), Vec::new())).expect("jsonencode");
        assert_eq!(as_string(encoded), "[1,2,3]");
    }
}